npm - @solytude/listmonk - Versions diffs - 1.0.0 - Mend

@solytude/listmonk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (108) hide show

package/LICENSE +21 -0
package/README.md +542 -0
package/dist/chunk-saezhne8.js +14 -0
package/dist/chunk-saezhne8.js.map +9 -0
package/dist/client.d.ts +430 -0
package/dist/errors/api.d.ts +178 -0
package/dist/errors/base.d.ts +47 -0
package/dist/errors/configuration.d.ts +49 -0
package/dist/errors/index.d.ts +13 -0
package/dist/errors/network.d.ts +69 -0
package/dist/errors/validation.d.ts +57 -0
package/dist/http/auth.d.ts +39 -0
package/dist/http/client.d.ts +149 -0
package/dist/http/hooks.d.ts +90 -0
package/dist/http/index.d.ts +10 -0
package/dist/http/resource.d.ts +100 -0
package/dist/http/sse.d.ts +36 -0
package/dist/http/url.d.ts +51 -0
package/dist/index.d.ts +64 -0
package/dist/index.js +16039 -0
package/dist/index.js.map +120 -0
package/dist/resources/admin/admin.d.ts +92 -0
package/dist/resources/admin/index.d.ts +10 -0
package/dist/resources/admin/schemas.d.ts +23 -0
package/dist/resources/admin/types.d.ts +29 -0
package/dist/resources/bounces/bounces.d.ts +262 -0
package/dist/resources/bounces/index.d.ts +10 -0
package/dist/resources/bounces/schemas.d.ts +86 -0
package/dist/resources/bounces/types.d.ts +37 -0
package/dist/resources/campaigns/campaigns.d.ts +339 -0
package/dist/resources/campaigns/index.d.ts +10 -0
package/dist/resources/campaigns/schemas.d.ts +374 -0
package/dist/resources/campaigns/types.d.ts +111 -0
package/dist/resources/dashboard/dashboard.d.ts +73 -0
package/dist/resources/dashboard/index.d.ts +10 -0
package/dist/resources/dashboard/schemas.d.ts +55 -0
package/dist/resources/dashboard/types.d.ts +22 -0
package/dist/resources/import/import.d.ts +215 -0
package/dist/resources/import/index.d.ts +10 -0
package/dist/resources/import/schemas.d.ts +109 -0
package/dist/resources/import/types.d.ts +72 -0
package/dist/resources/lists/index.d.ts +10 -0
package/dist/resources/lists/lists.d.ts +180 -0
package/dist/resources/lists/schemas.d.ts +176 -0
package/dist/resources/lists/types.d.ts +56 -0
package/dist/resources/maintenance/index.d.ts +10 -0
package/dist/resources/maintenance/maintenance.d.ts +92 -0
package/dist/resources/maintenance/schemas.d.ts +36 -0
package/dist/resources/maintenance/types.d.ts +31 -0
package/dist/resources/media/index.d.ts +10 -0
package/dist/resources/media/media.d.ts +198 -0
package/dist/resources/media/schemas.d.ts +48 -0
package/dist/resources/media/types.d.ts +48 -0
package/dist/resources/public/index.d.ts +10 -0
package/dist/resources/public/public.d.ts +111 -0
package/dist/resources/public/schemas.d.ts +52 -0
package/dist/resources/public/types.d.ts +30 -0
package/dist/resources/settings/index.d.ts +10 -0
package/dist/resources/settings/schemas.d.ts +374 -0
package/dist/resources/settings/settings.d.ts +106 -0
package/dist/resources/settings/types.d.ts +78 -0
package/dist/resources/subscribers/index.d.ts +10 -0
package/dist/resources/subscribers/schemas.d.ts +360 -0
package/dist/resources/subscribers/subscribers.d.ts +308 -0
package/dist/resources/subscribers/types.d.ts +113 -0
package/dist/resources/templates/index.d.ts +10 -0
package/dist/resources/templates/schemas.d.ts +110 -0
package/dist/resources/templates/templates.d.ts +225 -0
package/dist/resources/templates/types.d.ts +45 -0
package/dist/resources/tx/index.d.ts +10 -0
package/dist/resources/tx/schemas.d.ts +67 -0
package/dist/resources/tx/tx.d.ts +167 -0
package/dist/resources/tx/types.d.ts +88 -0
package/dist/schemas/common.d.ts +48 -0
package/dist/schemas/index.d.ts +6 -0
package/dist/testing/errors.d.ts +25 -0
package/dist/testing/factories/bounce.d.ts +43 -0
package/dist/testing/factories/campaign.d.ts +43 -0
package/dist/testing/factories/common.d.ts +54 -0
package/dist/testing/factories/index.d.ts +12 -0
package/dist/testing/factories/list.d.ts +43 -0
package/dist/testing/factories/media.d.ts +40 -0
package/dist/testing/factories/subscriber.d.ts +43 -0
package/dist/testing/factories/template.d.ts +40 -0
package/dist/testing/index.d.ts +39 -0
package/dist/testing/index.js +573 -0
package/dist/testing/index.js.map +32 -0
package/dist/testing/mock-client.d.ts +119 -0
package/dist/testing/mock-function.d.ts +28 -0
package/dist/testing/resources/admin.d.ts +20 -0
package/dist/testing/resources/bounces.d.ts +22 -0
package/dist/testing/resources/campaigns.d.ts +31 -0
package/dist/testing/resources/dashboard.d.ts +17 -0
package/dist/testing/resources/import.d.ts +19 -0
package/dist/testing/resources/index.d.ts +18 -0
package/dist/testing/resources/lists.d.ts +24 -0
package/dist/testing/resources/maintenance.d.ts +18 -0
package/dist/testing/resources/media.d.ts +21 -0
package/dist/testing/resources/public.d.ts +18 -0
package/dist/testing/resources/settings.d.ts +19 -0
package/dist/testing/resources/subscribers.d.ts +33 -0
package/dist/testing/resources/templates.d.ts +24 -0
package/dist/testing/resources/tx.d.ts +16 -0
package/dist/testing/types.d.ts +138 -0
package/dist/types/config.d.ts +59 -0
package/dist/types/index.d.ts +7 -0
package/dist/types/pagination.d.ts +37 -0
package/package.json +97 -0

package/dist/client.d.ts ADDED Viewed

@@ -0,0 +1,430 @@
+/**
+ * Main Listmonk client class.
+ *
+ * The primary entry point for the SDK. Validates configuration,
+ * creates the HTTP client, and provides access to resource modules.
+ *
+ * @module client
+ */
+import { HttpClient } from "./http/client";
+import type { ClientOptionsInput } from "./types/config";
+import { SubscribersResource } from "./resources/subscribers";
+import { ListsResource } from "./resources/lists";
+import { CampaignsResource } from "./resources/campaigns";
+import { TemplatesResource } from "./resources/templates";
+import { TransactionalResource } from "./resources/tx";
+import { MediaResource } from "./resources/media";
+import { ImportResource } from "./resources/import";
+import { BouncesResource } from "./resources/bounces";
+import { SettingsResource } from "./resources/settings";
+import { DashboardResource } from "./resources/dashboard";
+import { AdminResource } from "./resources/admin";
+import { MaintenanceResource } from "./resources/maintenance";
+import { PublicResource } from "./resources/public";
+import type { ServerHealth, ServerConfig } from "./resources/settings/types";
+/**
+ * Listmonk SDK client for interacting with the listmonk API.
+ *
+ * @example
+ * ```typescript
+ * import { Listmonk } from '@solytude/listmonk';
+ *
+ * const client = new Listmonk({
+ *   url: 'https://listmonk.example.com',
+ *   auth: {
+ *     username: 'admin',
+ *     password: 'secret',
+ *   },
+ * });
+ *
+ * // Use resource modules (to be added in subsequent specs)
+ * // const subscribers = await client.subscribers.list();
+ * ```
+ */
+export declare class Listmonk {
+    /** @internal The underlying HTTP client */
+    private readonly _httpClient;
+    /**
+     * Subscribers resource for managing subscriber lifecycle.
+     *
+     * @example
+     * ```typescript
+     * // Create a subscriber
+     * const subscriber = await client.subscribers.create({
+     *   email: 'john@example.com',
+     *   name: 'John Doe',
+     *   status: 'enabled',
+     * });
+     *
+     * // List subscribers
+     * for await (const sub of client.subscribers.listAll()) {
+     *   console.log(sub.email);
+     * }
+     * ```
+     */
+    readonly subscribers: SubscribersResource;
+    /**
+     * Lists resource for managing mailing lists.
+     *
+     * @example
+     * ```typescript
+     * // Create a list
+     * const list = await client.lists.create({
+     *   name: 'Newsletter',
+     *   type: 'public',
+     *   optin: 'double',
+     * });
+     *
+     * // List all lists
+     * for await (const l of client.lists.listAll()) {
+     *   console.log(l.name);
+     * }
+     * ```
+     */
+    readonly lists: ListsResource;
+    /**
+     * Campaigns resource for managing email campaigns.
+     *
+     * @example
+     * ```typescript
+     * // Create a campaign
+     * const campaign = await client.campaigns.create({
+     *   name: 'Weekly Newsletter',
+     *   subject: 'This Week in Tech',
+     *   lists: [1],
+     *   body: '<h1>Hello!</h1>',
+     *   content_type: 'html',
+     * });
+     *
+     * // Start the campaign
+     * await client.campaigns.updateStatus(campaign.id, 'running');
+     *
+     * // List all campaigns
+     * for await (const c of client.campaigns.listAll()) {
+     *   console.log(c.name, c.status);
+     * }
+     * ```
+     */
+    readonly campaigns: CampaignsResource;
+    /**
+     * Templates resource for managing email templates.
+     *
+     * @example
+     * ```typescript
+     * // Create a template
+     * const template = await client.templates.create({
+     *   name: 'Newsletter Template',
+     *   type: 'campaign',
+     *   body: '<html>{{ template "content" . }}</html>',
+     * });
+     *
+     * // List all templates
+     * for await (const t of client.templates.listAll()) {
+     *   console.log(t.name, t.is_default);
+     * }
+     *
+     * // Set as default
+     * await client.templates.setDefault(template.id);
+     * ```
+     */
+    readonly templates: TemplatesResource;
+    /**
+     * Transactional resource for sending application-triggered emails.
+     *
+     * @example
+     * ```typescript
+     * // Send to an existing subscriber
+     * await client.tx.send({
+     *   template_id: 2,
+     *   subscriber_email: 'user@example.com',
+     * });
+     *
+     * // Send with template data
+     * await client.tx.send({
+     *   template_id: 2,
+     *   subscriber_email: 'user@example.com',
+     *   data: {
+     *     order_id: '12345',
+     *     total: '$99.99',
+     *   },
+     * });
+     *
+     * // Send to external recipient
+     * await client.tx.send({
+     *   template_id: 2,
+     *   subscriber_mode: 'external',
+     *   subscriber_emails: ['guest@example.com'],
+     * });
+     *
+     * // Send with file attachment
+     * await client.tx.send({
+     *   template_id: 2,
+     *   subscriber_email: 'user@example.com',
+     *   attachments: [
+     *     { filename: 'invoice.pdf', content: pdfBuffer },
+     *   ],
+     * });
+     * ```
+     */
+    readonly tx: TransactionalResource;
+    /**
+     * Media resource for managing media files (images, PDFs, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Upload a file (Browser)
+     * const file = new File([content], 'hero.jpg', { type: 'image/jpeg' });
+     * const media = await client.media.upload(file);
+     * console.log(`URL: ${media.url}`);
+     *
+     * // Upload a file (Node.js)
+     * import { readFileSync } from 'fs';
+     * const media = await client.media.upload({
+     *   filename: 'hero.jpg',
+     *   content: readFileSync('./hero.jpg'),
+     * });
+     *
+     * // List all media
+     * const allMedia = await client.media.list();
+     *
+     * // Delete media
+     * const deleted = await client.media.remove(42);
+     * ```
+     */
+    readonly media: MediaResource;
+    /**
+     * Import resource for bulk subscriber import from CSV/ZIP files.
+     *
+     * @example
+     * ```typescript
+     * // Start import (Browser)
+     * const file = new File([csvContent], 'subscribers.csv');
+     * await client.import.start(file, {
+     *   mode: 'subscribe',
+     *   delimiter: ',',
+     *   lists: [1, 2],
+     * });
+     *
+     * // Start import (Node.js)
+     * import { readFileSync } from 'fs';
+     * await client.import.start(
+     *   { filename: 'subscribers.csv', content: readFileSync('./subscribers.csv') },
+     *   { mode: 'subscribe', delimiter: ',', lists: [1] }
+     * );
+     *
+     * // Poll for completion
+     * let status = await client.import.getStatus();
+     * while (status.status === 'processing') {
+     *   await new Promise(r => setTimeout(r, 1000));
+     *   status = await client.import.getStatus();
+     * }
+     *
+     * // Check logs
+     * const logs = await client.import.getLogs();
+     *
+     * // Cancel if needed
+     * await client.import.cancel();
+     * ```
+     */
+    readonly import: ImportResource;
+    /**
+     * Bounces resource for managing email bounce records.
+     *
+     * @example
+     * ```typescript
+     * // List bounces with filtering
+     * const bounces = await client.bounces.list({
+     *   campaign_id: 5,
+     *   order_by: 'created_at',
+     *   order: 'desc',
+     * });
+     *
+     * // Iterate all bounces
+     * for await (const bounce of client.bounces.listAll()) {
+     *   if (bounce.type === 'hard') {
+     *     console.log(`Hard bounce: ${bounce.email}`);
+     *   }
+     * }
+     *
+     * // Delete a specific bounce
+     * await client.bounces.remove(123);
+     *
+     * // Blocklist all bounced subscribers
+     * await client.bounces.blocklistBounced();
+     * ```
+     */
+    readonly bounces: BouncesResource;
+    /**
+     * Settings resource for managing server settings.
+     *
+     * @example
+     * ```typescript
+     * // Get all settings
+     * const settings = await client.settings.getAll();
+     * console.log(settings['app.site_name']);
+     *
+     * // Update settings
+     * const result = await client.settings.update({
+     *   'app.site_name': 'My Newsletter',
+     *   ...settings,
+     * });
+     *
+     * // Test SMTP configuration
+     * const logs = await client.settings.testSmtp({
+     *   host: 'smtp.example.com',
+     *   port: 587,
+     *   auth_protocol: 'login',
+     *   username: 'user',
+     *   password: 'pass',
+     *   tls_type: 'STARTTLS',
+     *   email: 'test@example.com',
+     * });
+     * ```
+     */
+    readonly settings: SettingsResource;
+    /**
+     * Dashboard resource for retrieving statistics.
+     *
+     * @example
+     * ```typescript
+     * // Get dashboard counts
+     * const counts = await client.dashboard.getCounts();
+     * console.log(`Total subscribers: ${counts.subscribers.total}`);
+     *
+     * // Get chart data
+     * const charts = await client.dashboard.getCharts();
+     * for (const point of charts.link_clicks) {
+     *   console.log(`${point.date}: ${point.count} clicks`);
+     * }
+     * ```
+     */
+    readonly dashboard: DashboardResource;
+    /**
+     * Admin resource for server administration.
+     *
+     * @example
+     * ```typescript
+     * // Reload application
+     * await client.admin.reload();
+     *
+     * // Get logs
+     * const logs = await client.admin.getLogs();
+     *
+     * // Stream events
+     * for await (const event of client.admin.getEventStream()) {
+     *   console.log(event.type, event.message);
+     * }
+     * ```
+     */
+    readonly admin: AdminResource;
+    /**
+     * Maintenance resource for cleanup operations.
+     *
+     * @example
+     * ```typescript
+     * // Delete blocklisted subscribers
+     * const result = await client.maintenance.gcSubscribers('blocklisted');
+     * console.log(`Deleted ${result.count} subscribers`);
+     *
+     * // Delete old analytics
+     * await client.maintenance.gcAnalytics('all', '2025-01-01T00:00:00Z');
+     * ```
+     */
+    readonly maintenance: MaintenanceResource;
+    /**
+     * Public resource for unauthenticated endpoints.
+     *
+     * @example
+     * ```typescript
+     * // Get public lists
+     * const lists = await client.public.getLists();
+     *
+     * // Submit subscription
+     * const result = await client.public.subscribe({
+     *   email: 'user@example.com',
+     *   list_uuids: [lists[0].uuid],
+     * });
+     *
+     * // Get CAPTCHA challenge
+     * const challenge = await client.public.getCaptchaChallenge();
+     * ```
+     */
+    readonly public: PublicResource;
+    /**
+     * Creates a new Listmonk client.
+     *
+     * @param options - Client configuration options
+     * @throws {ListmonkConfigurationError} If options are invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new Listmonk({
+     *   url: 'https://listmonk.example.com',
+     *   auth: { username: 'admin', password: 'secret' },
+     *   timeout: 60_000,  // Optional, default 30s
+     *   maxRetries: 5,    // Optional, default 3
+     *   debug: true,      // Optional, default false
+     * });
+     * ```
+     */
+    constructor(options: ClientOptionsInput);
+    /**
+     * Gets the underlying HTTP client.
+     * For internal use by resource modules.
+     * @internal
+     */
+    get httpClient(): HttpClient;
+    /**
+     * Checks server health (authenticated endpoint).
+     *
+     * Returns `true` if the server is healthy and reachable.
+     * Throws an error on network failure or authentication issues.
+     *
+     * @returns `true` if server is healthy
+     * @throws {ListmonkApiError} On API errors
+     * @throws {ListmonkNetworkError} On network failures
+     *
+     * @example
+     * ```typescript
+     * const healthy = await client.health();
+     * console.log(`Server healthy: ${healthy}`); // true
+     * ```
+     */
+    health(): Promise<ServerHealth>;
+    /**
+     * Checks server health (public endpoint, no authentication).
+     *
+     * Useful for health checks before authentication is configured
+     * or for public monitoring systems.
+     *
+     * @returns `true` if server is healthy
+     * @throws {ListmonkNetworkError} On network failures
+     *
+     * @example
+     * ```typescript
+     * const healthy = await client.publicHealth();
+     * console.log(`Server reachable: ${healthy}`); // true
+     * ```
+     */
+    publicHealth(): Promise<ServerHealth>;
+    /**
+     * Retrieves server configuration and capabilities.
+     *
+     * Returns information about the server version, enabled features,
+     * available updates, and runtime configuration.
+     *
+     * @returns Server configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = await client.getConfig();
+     * console.log(`Version: ${config.version}`);
+     * console.log(`Needs restart: ${config.needs_restart}`);
+     *
+     * if (config.update?.is_new) {
+     *   console.log(`Update available: ${config.update.release_version}`);
+     * }
+     * ```
+     */
+    getConfig(): Promise<ServerConfig>;
+}

package/dist/errors/api.d.ts ADDED Viewed

@@ -0,0 +1,178 @@
+/**
+ * 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 ADDED Viewed

@@ -0,0 +1,47 @@
+/**
+ * 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 ADDED Viewed

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