@upyo/maileroo 0.6.0-dev.0

package/dist/index.d.cts

@@ -0,0 +1,267 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Configuration interface for Maileroo transport connection settings.
+ *
+ * @example
+ * ```typescript
+ * const config: MailerooConfig = {
+ *   apiKey: "your-sending-key",
+ *   timeout: 30000,
+ *   retries: 3,
+ * };
+ * ```
+ *
+ * @since 0.6.0
+ */
+interface MailerooConfig {
+  /**
+   * Your Maileroo sending key.
+   *
+   * The key is sent as an `X-API-Key` HTTP header.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the Maileroo Email API.
+   *
+   * @default "https://smtp.maileroo.com/api/v2"
+   */
+  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;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether Maileroo should track opens and clicks for sent messages.
+   *
+   * When omitted, Maileroo applies the account default.
+   */
+  readonly tracking?: boolean;
+  /**
+   * Default Maileroo tags to apply to sent messages.
+   */
+  readonly tags?: Record<string, string>;
+}
+/**
+ * Resolved Maileroo configuration with defaults applied.
+ *
+ * @since 0.6.0
+ */
+type ResolvedMailerooConfig = Required<Omit<MailerooConfig, "tracking" | "tags">> & {
+  readonly tracking?: boolean;
+  readonly tags?: Record<string, string>;
+};
+/**
+ * Creates a resolved Maileroo configuration by applying default values.
+ *
+ * @param config The Maileroo configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ * @since 0.6.0
+ */
+declare function createMailerooConfig(config: MailerooConfig): ResolvedMailerooConfig;
+//#endregion
+//#region src/maileroo-transport.d.ts
+/**
+ * Maileroo transport implementation for sending emails via Maileroo API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@upyo/core";
+ * import { MailerooTransport } from "@upyo/maileroo";
+ *
+ * const transport = new MailerooTransport({
+ *   apiKey: "your-sending-key",
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Maileroo",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ *
+ * @since 0.6.0
+ */
+declare class MailerooTransport implements Transport<"maileroo"> {
+  readonly id = "maileroo";
+  /**
+   * The resolved Maileroo configuration used by this transport.
+   */
+  config: ResolvedMailerooConfig;
+  private httpClient;
+  /**
+   * Creates a new Maileroo transport instance.
+   *
+   * @param config Maileroo configuration including API key and options.
+   */
+  constructor(config: MailerooConfig);
+  /**
+   * Sends a single email message via Maileroo API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<"maileroo">>;
+  /**
+   * Sends multiple email messages sequentially via Maileroo API.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<"maileroo">>;
+}
+//#endregion
+//#region src/message-converter.d.ts
+/**
+ * Maileroo email address object.
+ *
+ * @since 0.6.0
+ */
+interface MailerooEmailAddress {
+  /** Email address. */
+  readonly address: string;
+  /** Optional display name. */
+  readonly display_name?: string;
+}
+/**
+ * Maileroo attachment object.
+ *
+ * @since 0.6.0
+ */
+interface MailerooAttachment {
+  /** Attachment filename. */
+  readonly file_name: string;
+  /** Attachment MIME type. */
+  readonly content_type?: string;
+  /** Base64-encoded attachment content. */
+  readonly content: string;
+  /** Whether this attachment is treated as inline content. */
+  readonly inline?: boolean;
+}
+/**
+ * Maileroo email object structure for API requests.
+ *
+ * @since 0.6.0
+ */
+interface MailerooEmail {
+  readonly from: MailerooEmailAddress;
+  readonly to: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly cc?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly bcc?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly reply_to?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly subject: string;
+  readonly html?: string;
+  readonly plain?: string;
+  readonly tracking?: boolean;
+  readonly tags?: Record<string, string>;
+  readonly headers?: Record<string, string>;
+  readonly attachments?: readonly MailerooAttachment[];
+}
+/**
+ * Converts an Upyo message to Maileroo API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Maileroo configuration.
+ * @returns JSON object ready for Maileroo API submission.
+ * @since 0.6.0
+ */
+//#endregion
+//#region src/http-client.d.ts
+/**
+ * Response from Maileroo API for sending a single message.
+ *
+ * @since 0.6.0
+ */
+interface MailerooResponse {
+  /** Whether Maileroo accepted the request. */
+  readonly success: boolean;
+  /** Human-readable response message. */
+  readonly message?: string;
+  /** Response payload from Maileroo. */
+  readonly data?: {
+    /** Maileroo reference ID for tracking the message. */
+    readonly reference_id?: string;
+  };
+}
+/**
+ * Error response from Maileroo API.
+ *
+ * @since 0.6.0
+ */
+interface MailerooError {
+  /** Error message from Maileroo. */
+  readonly message?: string;
+  /** Error detail from Maileroo. */
+  readonly error?: string;
+  /** Validation errors from Maileroo. */
+  readonly errors?: readonly unknown[];
+}
+/**
+ * Maileroo API error class for API-specific failures.
+ *
+ * @since 0.6.0
+ */
+declare class MailerooApiError extends Error {
+  readonly statusCode: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly attempts?: number;
+  /**
+   * Creates a Maileroo API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message: string, statusCode: number, retryAfterMilliseconds?: number, attempts?: number);
+}
+/**
+ * Maileroo request timeout error.
+ *
+ * @since 0.6.0
+ */
+declare class MailerooTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   *
+   * @since 0.6.0
+   */
+  readonly timeout: number;
+  /**
+   * Number of attempts made before this error was produced.
+   *
+   * @since 0.6.0
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a Maileroo request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout: number, attempts?: number);
+}
+/**
+ * HTTP client wrapper for Maileroo API requests.
+ *
+ * @since 0.6.0
+ */
+//#endregion
+export { MailerooApiError, MailerooAttachment, MailerooConfig, MailerooEmail, MailerooEmailAddress, MailerooError, MailerooResponse, MailerooTimeoutError, MailerooTransport, ResolvedMailerooConfig, createMailerooConfig };

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Configuration interface for Maileroo transport connection settings.
+ *
+ * @example
+ * ```typescript
+ * const config: MailerooConfig = {
+ *   apiKey: "your-sending-key",
+ *   timeout: 30000,
+ *   retries: 3,
+ * };
+ * ```
+ *
+ * @since 0.6.0
+ */
+interface MailerooConfig {
+  /**
+   * Your Maileroo sending key.
+   *
+   * The key is sent as an `X-API-Key` HTTP header.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the Maileroo Email API.
+   *
+   * @default "https://smtp.maileroo.com/api/v2"
+   */
+  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;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether Maileroo should track opens and clicks for sent messages.
+   *
+   * When omitted, Maileroo applies the account default.
+   */
+  readonly tracking?: boolean;
+  /**
+   * Default Maileroo tags to apply to sent messages.
+   */
+  readonly tags?: Record<string, string>;
+}
+/**
+ * Resolved Maileroo configuration with defaults applied.
+ *
+ * @since 0.6.0
+ */
+type ResolvedMailerooConfig = Required<Omit<MailerooConfig, "tracking" | "tags">> & {
+  readonly tracking?: boolean;
+  readonly tags?: Record<string, string>;
+};
+/**
+ * Creates a resolved Maileroo configuration by applying default values.
+ *
+ * @param config The Maileroo configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ * @since 0.6.0
+ */
+declare function createMailerooConfig(config: MailerooConfig): ResolvedMailerooConfig;
+//#endregion
+//#region src/maileroo-transport.d.ts
+/**
+ * Maileroo transport implementation for sending emails via Maileroo API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@upyo/core";
+ * import { MailerooTransport } from "@upyo/maileroo";
+ *
+ * const transport = new MailerooTransport({
+ *   apiKey: "your-sending-key",
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Maileroo",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ *
+ * @since 0.6.0
+ */
+declare class MailerooTransport implements Transport<"maileroo"> {
+  readonly id = "maileroo";
+  /**
+   * The resolved Maileroo configuration used by this transport.
+   */
+  config: ResolvedMailerooConfig;
+  private httpClient;
+  /**
+   * Creates a new Maileroo transport instance.
+   *
+   * @param config Maileroo configuration including API key and options.
+   */
+  constructor(config: MailerooConfig);
+  /**
+   * Sends a single email message via Maileroo API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<"maileroo">>;
+  /**
+   * Sends multiple email messages sequentially via Maileroo API.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<"maileroo">>;
+}
+//#endregion
+//#region src/message-converter.d.ts
+/**
+ * Maileroo email address object.
+ *
+ * @since 0.6.0
+ */
+interface MailerooEmailAddress {
+  /** Email address. */
+  readonly address: string;
+  /** Optional display name. */
+  readonly display_name?: string;
+}
+/**
+ * Maileroo attachment object.
+ *
+ * @since 0.6.0
+ */
+interface MailerooAttachment {
+  /** Attachment filename. */
+  readonly file_name: string;
+  /** Attachment MIME type. */
+  readonly content_type?: string;
+  /** Base64-encoded attachment content. */
+  readonly content: string;
+  /** Whether this attachment is treated as inline content. */
+  readonly inline?: boolean;
+}
+/**
+ * Maileroo email object structure for API requests.
+ *
+ * @since 0.6.0
+ */
+interface MailerooEmail {
+  readonly from: MailerooEmailAddress;
+  readonly to: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly cc?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly bcc?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly reply_to?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly subject: string;
+  readonly html?: string;
+  readonly plain?: string;
+  readonly tracking?: boolean;
+  readonly tags?: Record<string, string>;
+  readonly headers?: Record<string, string>;
+  readonly attachments?: readonly MailerooAttachment[];
+}
+/**
+ * Converts an Upyo message to Maileroo API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Maileroo configuration.
+ * @returns JSON object ready for Maileroo API submission.
+ * @since 0.6.0
+ */
+//#endregion
+//#region src/http-client.d.ts
+/**
+ * Response from Maileroo API for sending a single message.
+ *
+ * @since 0.6.0
+ */
+interface MailerooResponse {
+  /** Whether Maileroo accepted the request. */
+  readonly success: boolean;
+  /** Human-readable response message. */
+  readonly message?: string;
+  /** Response payload from Maileroo. */
+  readonly data?: {
+    /** Maileroo reference ID for tracking the message. */
+    readonly reference_id?: string;
+  };
+}
+/**
+ * Error response from Maileroo API.
+ *
+ * @since 0.6.0
+ */
+interface MailerooError {
+  /** Error message from Maileroo. */
+  readonly message?: string;
+  /** Error detail from Maileroo. */
+  readonly error?: string;
+  /** Validation errors from Maileroo. */
+  readonly errors?: readonly unknown[];
+}
+/**
+ * Maileroo API error class for API-specific failures.
+ *
+ * @since 0.6.0
+ */
+declare class MailerooApiError extends Error {
+  readonly statusCode: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly attempts?: number;
+  /**
+   * Creates a Maileroo API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message: string, statusCode: number, retryAfterMilliseconds?: number, attempts?: number);
+}
+/**
+ * Maileroo request timeout error.
+ *
+ * @since 0.6.0
+ */
+declare class MailerooTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   *
+   * @since 0.6.0
+   */
+  readonly timeout: number;
+  /**
+   * Number of attempts made before this error was produced.
+   *
+   * @since 0.6.0
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a Maileroo request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout: number, attempts?: number);
+}
+/**
+ * HTTP client wrapper for Maileroo API requests.
+ *
+ * @since 0.6.0
+ */
+//#endregion
+export { MailerooApiError, MailerooAttachment, MailerooConfig, MailerooEmail, MailerooEmailAddress, MailerooError, MailerooResponse, MailerooTimeoutError, MailerooTransport, ResolvedMailerooConfig, createMailerooConfig };