@solytude/listmonk 1.0.0

package/dist/errors/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Error class exports for the listmonk SDK.
+ *
+ * All SDK errors extend the base `ListmonkError` class, enabling
+ * unified error handling via `instanceof ListmonkError`.
+ *
+ * @module errors
+ */
+export { ListmonkError } from "./base";
+export { ListmonkApiError, ListmonkBadRequestError, ListmonkAuthenticationError, ListmonkPermissionDeniedError, ListmonkNotFoundError, ListmonkRateLimitError, ListmonkInternalServerError, } from "./api";
+export { ListmonkValidationError } from "./validation";
+export { ListmonkNetworkError, ListmonkTimeoutError } from "./network";
+export { ListmonkConfigurationError } from "./configuration";

package/dist/errors/network.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Network-level errors for fetch failures.
+ *
+ * Thrown when network communication fails, including DNS resolution,
+ * connection errors, and request timeouts.
+ *
+ * @module errors/network
+ */
+import { ListmonkError } from "./base";
+/**
+ * Error thrown when a network-level failure occurs.
+ *
+ * This includes:
+ * - DNS resolution failures
+ * - Connection refused/reset
+ * - TLS/SSL errors
+ * - Other fetch-level failures
+ *
+ * Network errors are generally retryable.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.subscribers.list();
+ * } catch (error) {
+ *   if (error instanceof ListmonkNetworkError) {
+ *     console.error('Network error:', error.message);
+ *     console.error('Underlying cause:', error.cause);
+ *   }
+ * }
+ * ```
+ */
+export declare class ListmonkNetworkError extends ListmonkError {
+    readonly name: string;
+}
+/**
+ * Error thrown when a request times out.
+ *
+ * Extends ListmonkNetworkError as timeouts are a specific type
+ * of network failure. Includes the timeout value for debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.subscribers.list({ timeout: 5000 });
+ * } catch (error) {
+ *   if (error instanceof ListmonkTimeoutError) {
+ *     console.error(`Request timed out after ${error.timeout}ms`);
+ *   }
+ * }
+ * ```
+ */
+export declare class ListmonkTimeoutError extends ListmonkNetworkError {
+    readonly name: string;
+    /**
+     * The timeout value in milliseconds that was exceeded.
+     */
+    readonly timeout: number;
+    /**
+     * Creates a new timeout error.
+     *
+     * @param message - Description of the timeout
+     * @param timeout - The timeout value in milliseconds
+     * @param options - Optional error options
+     */
+    constructor(message: string, timeout: number, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors/validation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Validation error for Zod schema failures.
+ *
+ * Thrown when API responses or request data fails Zod validation,
+ * indicating a mismatch between expected and actual data structures.
+ *
+ * @module errors/validation
+ */
+import type { ZodError } from "zod";
+import { ListmonkError } from "./base";
+/**
+ * Error thrown when data validation fails.
+ *
+ * Contains the Zod error with detailed validation issues,
+ * the original invalid data, and the API endpoint if applicable.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.subscribers.get(123);
+ * } catch (error) {
+ *   if (error instanceof ListmonkValidationError) {
+ *     console.error('Validation failed:', error.zodError?.issues);
+ *     console.error('Invalid data:', error.data);
+ *   }
+ * }
+ * ```
+ */
+export declare class ListmonkValidationError extends ListmonkError {
+    readonly name: string;
+    /**
+     * The Zod validation error with detailed issue information.
+     */
+    readonly zodError?: ZodError;
+    /**
+     * The data that failed validation.
+     */
+    readonly data?: unknown;
+    /**
+     * The API endpoint where validation failed, if applicable.
+     */
+    readonly endpoint?: string;
+    /**
+     * Creates a new validation error.
+     *
+     * @param message - Description of the validation failure
+     * @param options - Optional validation details
+     * @param options.zodError - The Zod error with detailed issues
+     * @param options.data - The data that failed validation
+     * @param options.endpoint - The API endpoint if this was a response validation
+     */
+    constructor(message: string, options?: {
+        zodError?: ZodError;
+        data?: unknown;
+        endpoint?: string;
+    });
+}

package/dist/http/auth.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Basic Auth encoding utilities.
+ *
+ * Provides functions for encoding credentials for HTTP Basic Authentication.
+ *
+ * @module http/auth
+ */
+/**
+ * Encodes username and password for Basic Auth.
+ *
+ * @param username - The username
+ * @param password - The password
+ * @returns Base64-encoded credentials string
+ *
+ * @example
+ * ```typescript
+ * const encoded = encodeBasicAuth('admin', 'secret');
+ * // Returns: 'YWRtaW46c2VjcmV0'
+ * ```
+ */
+export declare function encodeBasicAuth(username: string, password: string): string;
+/**
+ * Creates a complete Basic Auth header value.
+ *
+ * @param username - The username
+ * @param password - The password
+ * @returns Complete Authorization header value (e.g., "Basic YWRtaW46c2VjcmV0")
+ *
+ * @example
+ * ```typescript
+ * const header = createAuthHeader('admin', 'secret');
+ * // Returns: 'Basic YWRtaW46c2VjcmV0'
+ *
+ * fetch(url, {
+ *   headers: { Authorization: header }
+ * });
+ * ```
+ */
+export declare function createAuthHeader(username: string, password: string): string;

package/dist/http/client.d.ts

@@ -0,0 +1,149 @@
+/**
+ * HTTP client for making authenticated requests to listmonk.
+ *
+ * Handles authentication, retry logic, timeout, hooks, and error handling.
+ *
+ * @module http/client
+ */
+import type { z } from "zod";
+import type { RequestHook, ResponseHook, HttpMethod } from "./hooks";
+import type { AuthCredentials, FetchLike } from "../types/config";
+/**
+ * Options for individual HTTP requests.
+ */
+export interface RequestOptions {
+    /** HTTP method */
+    method: HttpMethod;
+    /** API endpoint path (e.g., '/api/subscribers') */
+    path: string;
+    /** Request body (will be JSON-serialized) */
+    body?: unknown;
+    /** Query parameters */
+    query?: Record<string, unknown>;
+    /** Per-request timeout override in milliseconds */
+    timeout?: number;
+    /** User-provided abort signal */
+    signal?: AbortSignal;
+    /** Skip automatic retry for this request */
+    skipRetry?: boolean;
+    /**
+     * FormData for multipart requests (e.g., file attachments).
+     * When set, body is ignored and Content-Type is not set
+     * (browser/runtime will set it with proper boundary).
+     */
+    multipart?: FormData;
+    /**
+     * Skip authentication for this request.
+     * Used for public endpoints that don't require authorization.
+     */
+    skipAuth?: boolean;
+}
+/**
+ * HTTP client for the listmonk SDK.
+ *
+ * Provides authenticated HTTP requests with automatic retry,
+ * timeout handling, and extensibility hooks.
+ */
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly debug;
+    private readonly fetch;
+    private readonly requestHooks;
+    private readonly responseHooks;
+    private readonly retryConfig;
+    /**
+     * Creates a new HTTP client.
+     *
+     * @param options - Client configuration options
+     */
+    constructor(options: {
+        url: string;
+        auth: AuthCredentials;
+        timeout?: number;
+        maxRetries?: number;
+        debug?: boolean;
+        fetch?: FetchLike;
+        onRequest?: RequestHook;
+        onResponse?: ResponseHook;
+    });
+    /**
+     * Makes an HTTP request with retry, timeout, and validation.
+     *
+     * @param options - Request options
+     * @param schema - Zod schema for response validation
+     * @returns Validated response data
+     * @throws {ListmonkApiError} On API errors (4xx, 5xx)
+     * @throws {ListmonkNetworkError} On network failures
+     * @throws {ListmonkTimeoutError} On request timeout
+     * @throws {ListmonkValidationError} On response validation failure
+     */
+    request<T>(options: RequestOptions, schema?: z.ZodType<T>): Promise<T>;
+    /**
+     * Makes a raw HTTP request returning the Response object directly.
+     *
+     * Useful for streaming responses like SSE where you need access
+     * to the response body stream.
+     *
+     * @param options - Request options
+     * @returns The raw Response object
+     * @throws {ListmonkApiError} On API errors (4xx, 5xx)
+     * @throws {ListmonkNetworkError} On network failures
+     * @throws {ListmonkTimeoutError} On request timeout
+     */
+    requestRaw(options: RequestOptions): Promise<Response>;
+    /**
+     * Makes a fetch request with timeout handling.
+     * Uses AbortSignal.timeout() for cleaner timeout management (Node 17.3+).
+     */
+    private fetchWithTimeout;
+    /**
+     * Merges timeout and user abort signals.
+     * Uses AbortSignal.any() which is available in Node 20+ and handles
+     * cleanup automatically, avoiding memory leaks from event listeners.
+     */
+    private mergeSignals;
+    /**
+     * Parses response body as JSON.
+     */
+    private parseResponseBody;
+    /**
+     * Validates response data against a Zod schema.
+     */
+    private validateResponse;
+    /**
+     * Calculates backoff delay with jitter.
+     * Jitter is applied before capping to ensure the final delay never exceeds maxDelay.
+     */
+    private calculateBackoffDelay;
+    /**
+     * Checks if an error is retryable.
+     */
+    private isRetryableError;
+    /**
+     * Checks if an error is a fetch error (network issue).
+     */
+    private isFetchError;
+    /**
+     * Gets retry-after value in milliseconds from error.
+     */
+    private getRetryAfterMs;
+    /**
+     * Checks for deprecation headers and logs warnings.
+     */
+    private checkDeprecationHeaders;
+    /**
+     * Logs debug information with redaction.
+     */
+    private debugLog;
+    /**
+     * Redacts sensitive information from headers.
+     */
+    private redactHeaders;
+    /**
+     * Sleeps for the specified duration.
+     */
+    private sleep;
+}

package/dist/http/hooks.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Request and response hook types for extensibility.
+ *
+ * Hooks allow SDK users to observe and optionally modify requests,
+ * and observe responses for logging, metrics, or custom handling.
+ *
+ * @module http/hooks
+ */
+/**
+ * HTTP methods supported by the SDK.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+/**
+ * Information about an outgoing request.
+ *
+ * Passed to request hooks before the request is sent.
+ */
+export interface RequestInfo {
+    /** HTTP method */
+    readonly method: HttpMethod;
+    /** Full request URL */
+    readonly url: string;
+    /** Request headers (mutable for modification) */
+    readonly headers: Headers;
+    /** Request body (if applicable) */
+    readonly body?: unknown;
+}
+/**
+ * Information about a received response.
+ *
+ * Passed to response hooks after the response is received.
+ */
+export interface ResponseInfo {
+    /** HTTP status code */
+    readonly status: number;
+    /** Response headers */
+    readonly headers: Headers;
+    /** Parsed response body */
+    readonly body: unknown;
+    /** X-Request-ID header value if present */
+    readonly requestId?: string;
+    /** Request duration in milliseconds */
+    readonly duration: number;
+    /** API endpoint that was called */
+    readonly endpoint: string;
+}
+/**
+ * Hook called before each request is sent.
+ *
+ * Can modify the request by returning a modified RequestInfo object.
+ * Return void or undefined to pass through unchanged.
+ *
+ * @example
+ * ```typescript
+ * const addTimingHeader: RequestHook = (info) => {
+ *   info.headers.set('X-Request-Start', Date.now().toString());
+ *   return info;
+ * };
+ * ```
+ */
+export type RequestHook = (info: RequestInfo) => RequestInfo | undefined;
+/**
+ * Hook called after each response is received.
+ *
+ * Observation only - cannot modify the response.
+ * Useful for logging, metrics, or error tracking.
+ *
+ * @example
+ * ```typescript
+ * const logResponse: ResponseHook = (info) => {
+ *   console.log(`${info.endpoint}: ${info.status} (${info.duration}ms)`);
+ * };
+ * ```
+ */
+export type ResponseHook = (info: ResponseInfo) => void;
+/**
+ * Applies request hooks in sequence, accumulating modifications.
+ *
+ * @param hooks - Array of request hooks to apply
+ * @param info - Initial request info
+ * @returns Modified request info (or original if no modifications)
+ */
+export declare function applyRequestHooks(hooks: RequestHook[], info: RequestInfo): RequestInfo;
+/**
+ * Applies response hooks in sequence.
+ *
+ * @param hooks - Array of response hooks to apply
+ * @param info - Response info to observe
+ */
+export declare function applyResponseHooks(hooks: ResponseHook[], info: ResponseInfo): void;

package/dist/http/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP module exports.
+ *
+ * @module http
+ */
+export { HttpClient, type RequestOptions } from "./client";
+export { encodeBasicAuth, createAuthHeader } from "./auth";
+export { normalizeBaseUrl, buildUrl, validateHttpsUrl } from "./url";
+export { type HttpMethod, type RequestInfo, type ResponseInfo, type RequestHook, type ResponseHook, applyRequestHooks, applyResponseHooks, } from "./hooks";
+export { APIResource, type ResourceRequestOptions } from "./resource";

package/dist/http/resource.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Base class for API resource modules.
+ *
+ * Provides convenience methods for HTTP requests that resource modules
+ * can use to interact with the listmonk API.
+ *
+ * @module http/resource
+ */
+import type { z } from "zod";
+import type { HttpClient, RequestOptions } from "./client";
+/**
+ * Options for resource methods (excluding method and path).
+ */
+export type ResourceRequestOptions = Omit<RequestOptions, "method" | "path">;
+/**
+ * Abstract base class for all listmonk resource modules.
+ *
+ * Resource modules (subscribers, lists, campaigns, etc.) extend this class
+ * to get access to HTTP request methods.
+ *
+ * @example
+ * ```typescript
+ * class SubscribersResource extends APIResource {
+ *   // Use different public method names to avoid shadowing protected methods
+ *   async retrieve(id: number): Promise<Subscriber> {
+ *     return this.get(`/api/subscribers/${id}`, SubscriberSchema);
+ *   }
+ *
+ *   async create(data: CreateSubscriber): Promise<Subscriber> {
+ *     return this.post('/api/subscribers', SubscriberSchema, { body: data });
+ *   }
+ *
+ *   async list(options?: ListOptions): Promise<SubscriberPage> {
+ *     return this.get('/api/subscribers', SubscriberPageSchema, { query: options });
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * The protected methods (get, post, put, delete) should not be shadowed by
+ * public methods with the same name. Use alternative names like `retrieve`,
+ * `list`, `remove` for public CRUD methods.
+ */
+export declare abstract class APIResource {
+    /**
+     * The HTTP client instance.
+     * @internal
+     */
+    protected readonly _client: HttpClient;
+    /**
+     * Creates a new resource instance.
+     *
+     * @param client - The HTTP client to use for requests
+     */
+    constructor(client: HttpClient);
+    /**
+     * Makes a GET request to the specified path.
+     *
+     * @param path - API endpoint path
+     * @param schema - Optional Zod schema for response validation
+     * @param options - Additional request options
+     * @returns Response data
+     */
+    protected get<T>(path: string, schema?: z.ZodType<T>, options?: ResourceRequestOptions): Promise<T>;
+    protected get<T>(path: string, options?: ResourceRequestOptions): Promise<T>;
+    /**
+     * Makes a POST request to the specified path.
+     *
+     * @param path - API endpoint path
+     * @param schema - Optional Zod schema for response validation
+     * @param options - Additional request options (including body)
+     * @returns Response data
+     */
+    protected post<T>(path: string, schema?: z.ZodType<T>, options?: ResourceRequestOptions): Promise<T>;
+    protected post<T>(path: string, options?: ResourceRequestOptions): Promise<T>;
+    /**
+     * Makes a PUT request to the specified path.
+     *
+     * @param path - API endpoint path
+     * @param schema - Optional Zod schema for response validation
+     * @param options - Additional request options (including body)
+     * @returns Response data
+     */
+    protected put<T>(path: string, schema?: z.ZodType<T>, options?: ResourceRequestOptions): Promise<T>;
+    protected put<T>(path: string, options?: ResourceRequestOptions): Promise<T>;
+    /**
+     * Makes a DELETE request to the specified path.
+     *
+     * @param path - API endpoint path
+     * @param schema - Optional Zod schema for response validation
+     * @param options - Additional request options
+     * @returns Response data
+     */
+    protected delete<T>(path: string, schema?: z.ZodType<T>, options?: ResourceRequestOptions): Promise<T>;
+    protected delete<T>(path: string, options?: ResourceRequestOptions): Promise<T>;
+    /**
+     * Resolves overloaded arguments for schema and options.
+     */
+    private resolveArgs;
+}

package/dist/http/sse.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Server-Sent Events (SSE) streaming utilities.
+ *
+ * Provides AsyncGenerator-based SSE parsing for use with listmonk's
+ * real-time event stream endpoint.
+ *
+ * @module http/sse
+ */
+import type { z } from "zod";
+/**
+ * Options for SSE streaming.
+ */
+export interface SSEOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Parses Server-Sent Events from a Response stream.
+ *
+ * This is a low-level utility that yields parsed and validated
+ * events from an SSE response body.
+ *
+ * @param response - The fetch Response with an SSE body stream
+ * @param schema - Zod schema for validating event data
+ * @yields Validated event objects
+ * @throws {ListmonkValidationError} If event data fails schema validation
+ *
+ * @example
+ * ```typescript
+ * const response = await client.requestRaw({ method: 'GET', path: '/api/events' });
+ * for await (const event of streamSSE(response, SSEEventSchema)) {
+ *   console.log(event.type, event.message);
+ * }
+ * ```
+ */
+export declare function streamSSE<T>(response: Response, schema: z.ZodType<T>): AsyncGenerator<T, void, undefined>;

package/dist/http/url.d.ts

@@ -0,0 +1,51 @@
+/**
+ * URL normalization and path building utilities.
+ *
+ * Provides functions for URL validation, normalization, and building
+ * complete request URLs with query parameters.
+ *
+ * @module http/url
+ */
+/**
+ * Validates that a URL uses HTTPS.
+ *
+ * Throws ListmonkConfigurationError if the URL is invalid or uses HTTP.
+ *
+ * @param url - The URL to validate
+ * @throws {ListmonkConfigurationError} If URL is invalid or not HTTPS
+ *
+ * @example
+ * ```typescript
+ * validateHttpsUrl('https://listmonk.example.com'); // OK
+ * validateHttpsUrl('http://example.com'); // Throws
+ * ```
+ */
+export declare function validateHttpsUrl(url: string): void;
+/**
+ * Normalizes a base URL by removing trailing slashes.
+ *
+ * @param url - The URL to normalize
+ * @returns URL with trailing slashes removed
+ *
+ * @example
+ * ```typescript
+ * normalizeBaseUrl('https://example.com/'); // 'https://example.com'
+ * normalizeBaseUrl('https://example.com/api/'); // 'https://example.com/api'
+ * ```
+ */
+export declare function normalizeBaseUrl(url: string): string;
+/**
+ * Builds a complete URL from base URL, path, and optional query parameters.
+ *
+ * @param baseUrl - The base URL (should be normalized)
+ * @param path - The API path (e.g., '/api/subscribers')
+ * @param query - Optional query parameters
+ * @returns Complete URL string
+ *
+ * @example
+ * ```typescript
+ * buildUrl('https://api.example.com', '/subscribers', { page: 1 });
+ * // Returns: 'https://api.example.com/subscribers?page=1'
+ * ```
+ */
+export declare function buildUrl(baseUrl: string, path: string, query?: Record<string, unknown>): string;