@maloma/listmonk 1.0.0 → 1.0.1

package/dist/errors/api.d.ts

@@ -1,178 +0,0 @@
-/**
- * API error classes for HTTP response failures.
- *
- * Provides a hierarchy of errors for different HTTP status codes,
- * with a factory method for automatic error type selection.
- *
- * @module errors/api
- */
-import { ListmonkError } from "./base";
-/**
- * Base error for all HTTP API failures (4xx and 5xx responses).
- *
- * Contains the HTTP status code, response body, request ID,
- * and endpoint information for debugging.
- *
- * @example
- * ```typescript
- * try {
- *   await client.subscribers.get(123);
- * } catch (error) {
- *   if (error instanceof ListmonkApiError) {
- *     console.error(`API error ${error.status}:`, error.message);
- *     console.error('Request ID:', error.requestId);
- *   }
- * }
- * ```
- */
-export declare class ListmonkApiError extends ListmonkError {
-    readonly name: string;
-    /**
-     * HTTP status code of the response.
-     */
-    readonly status: number;
-    /**
-     * Parsed response body.
-     */
-    readonly body: unknown;
-    /**
-     * The API endpoint that failed.
-     */
-    readonly endpoint: string;
-    /**
-     * The X-Request-ID header value, if present.
-     * Useful for correlating with server logs.
-     */
-    readonly requestId?: string;
-    /**
-     * The response headers.
-     */
-    readonly headers?: Headers;
-    /**
-     * Creates a new API error.
-     *
-     * @param message - Human-readable error message
-     * @param status - HTTP status code
-     * @param body - Parsed response body
-     * @param endpoint - The API endpoint that failed
-     * @param requestId - Optional X-Request-ID value
-     * @param headers - Optional response headers
-     */
-    constructor(message: string, status: number, body: unknown, endpoint: string, requestId?: string, headers?: Headers);
-    /**
-     * Creates the appropriate error subclass based on HTTP status code.
-     *
-     * @param response - The fetch Response object
-     * @param body - Parsed response body
-     * @param endpoint - The API endpoint that was called
-     * @returns The appropriate ListmonkApiError subclass
-     */
-    static fromResponse(response: Response, body: unknown, endpoint: string): ListmonkApiError;
-}
-/**
- * Error thrown for HTTP 400 Bad Request responses.
- *
- * Indicates the request was malformed or contained invalid data.
- */
-export declare class ListmonkBadRequestError extends ListmonkApiError {
-    readonly name: string;
-    readonly status: number;
-    /**
-     * Creates a new bad request error.
-     *
-     * @param message - Error message
-     * @param body - Response body with validation details
-     * @param endpoint - The API endpoint
-     * @param requestId - Optional X-Request-ID
-     * @param headers - Optional response headers
-     */
-    constructor(message: string, body: unknown, endpoint: string, requestId?: string, headers?: Headers);
-}
-/**
- * Error thrown for HTTP 401 Unauthorized responses.
- *
- * Indicates the request lacked valid authentication credentials.
- */
-export declare class ListmonkAuthenticationError extends ListmonkApiError {
-    readonly name: string;
-    readonly status: number;
-    /**
-     * Creates a new authentication error.
-     *
-     * @param message - Error message
-     * @param endpoint - The API endpoint
-     * @param requestId - Optional X-Request-ID
-     * @param headers - Optional response headers
-     */
-    constructor(message: string, endpoint: string, requestId?: string, headers?: Headers);
-}
-/**
- * Error thrown for HTTP 403 Forbidden responses.
- *
- * Indicates the authenticated user lacks permission for the requested action.
- */
-export declare class ListmonkPermissionDeniedError extends ListmonkApiError {
-    readonly name: string;
-    readonly status: number;
-    /**
-     * Creates a new permission denied error.
-     *
-     * @param message - Error message
-     * @param endpoint - The API endpoint
-     * @param requestId - Optional X-Request-ID
-     * @param headers - Optional response headers
-     */
-    constructor(message: string, endpoint: string, requestId?: string, headers?: Headers);
-}
-/**
- * Error thrown for HTTP 404 Not Found responses.
- *
- * Indicates the requested resource does not exist.
- */
-export declare class ListmonkNotFoundError extends ListmonkApiError {
-    readonly name: string;
-    readonly status: number;
-    /**
-     * Creates a new not found error.
-     *
-     * @param message - Error message
-     * @param endpoint - The API endpoint
-     * @param requestId - Optional X-Request-ID
-     * @param headers - Optional response headers
-     */
-    constructor(message: string, endpoint: string, requestId?: string, headers?: Headers);
-}
-/**
- * Error thrown for HTTP 429 Too Many Requests responses.
- *
- * Indicates the rate limit has been exceeded. Check the `retryAfter`
- * property for the recommended wait time before retrying.
- */
-export declare class ListmonkRateLimitError extends ListmonkApiError {
-    readonly name: string;
-    readonly status: number;
-    /**
-     * Seconds to wait before retrying (from Retry-After header).
-     * Capped at 60 seconds per SDK requirements.
-     */
-    readonly retryAfter?: number;
-    /**
-     * Creates a new rate limit error.
-     *
-     * @param message - Error message
-     * @param body - Response body
-     * @param endpoint - The API endpoint
-     * @param retryAfter - Seconds to wait before retrying (capped at 60)
-     * @param requestId - Optional X-Request-ID
-     * @param headers - Optional response headers
-     */
-    constructor(message: string, body: unknown, endpoint: string, retryAfter?: number, requestId?: string, headers?: Headers);
-}
-/**
- * Error thrown for HTTP 5xx Server Error responses.
- *
- * Indicates a server-side error. These errors are typically retryable.
- */
-export declare class ListmonkInternalServerError extends ListmonkApiError {
-    readonly name: string;
-}

package/dist/errors/base.d.ts

@@ -1,47 +0,0 @@
-/**
- * Base error class for all listmonk SDK errors.
- *
- * All SDK-specific errors extend this class, enabling unified error handling
- * via `instanceof ListmonkError`.
- *
- * @example
- * ```typescript
- * try {
- *   await client.subscribers.get(123);
- * } catch (error) {
- *   if (error instanceof ListmonkError) {
- *     console.error('SDK error:', error.message);
- *   }
- * }
- * ```
- *
- * @module errors/base
- */
-/**
- * Abstract base class for all listmonk SDK errors.
- *
- * Provides proper prototype chain maintenance and stack trace capture
- * for all SDK error types.
- */
-export declare abstract class ListmonkError extends Error {
-    /**
-     * The name of the error class.
-     * Must be overridden by subclasses to provide a unique identifier.
-     */
-    abstract readonly name: string;
-    /**
-     * The underlying cause of this error, if any.
-     * Useful for error chaining when wrapping lower-level errors.
-     */
-    readonly cause?: unknown;
-    /**
-     * Creates a new ListmonkError instance.
-     *
-     * @param message - Human-readable error message
-     * @param options - Optional error options
-     * @param options.cause - The underlying error that caused this error
-     */
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}

package/dist/errors/configuration.d.ts

@@ -1,49 +0,0 @@
-/**
- * Configuration error for invalid SDK options.
- *
- * Thrown when the SDK is initialized with invalid configuration,
- * such as missing credentials or invalid URLs.
- *
- * @module errors/configuration
- */
-import { ListmonkError } from "./base";
-/**
- * Error thrown when SDK configuration is invalid.
- *
- * Common scenarios:
- * - Missing or invalid URL
- * - HTTP URL instead of HTTPS
- * - Missing authentication credentials
- * - Invalid timeout or retry values
- *
- * @example
- * ```typescript
- * try {
- *   const client = new Listmonk({
- *     url: 'http://example.com', // HTTP not allowed
- *     auth: { username: 'user', password: 'pass' },
- *   });
- * } catch (error) {
- *   if (error instanceof ListmonkConfigurationError) {
- *     console.error(`Config error in ${error.field}:`, error.message);
- *   }
- * }
- * ```
- */
-export declare class ListmonkConfigurationError extends ListmonkError {
-    readonly name: string;
-    /**
-     * The configuration field that caused the error, if identifiable.
-     */
-    readonly field?: string;
-    /**
-     * Creates a new configuration error.
-     *
-     * @param message - Description of the configuration problem
-     * @param options - Optional additional details
-     * @param options.field - The specific field that is invalid
-     */
-    constructor(message: string, options?: {
-        field?: string;
-    });
-}

package/dist/errors/index.d.ts

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,69 +0,0 @@
-/**
- * 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

@@ -1,57 +0,0 @@
-/**
- * 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

@@ -1,39 +0,0 @@
-/**
- * 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

@@ -1,149 +0,0 @@
-/**
- * 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

@@ -1,90 +0,0 @@
-/**
- * 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;