@solytude/listmonk 1.0.0

package/dist/resources/settings/settings.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Settings resource for managing server settings.
+ *
+ * @module resources/settings
+ */
+import { APIResource } from "../../http/resource";
+import type { Settings, SettingsUpdateResponse, SmtpTestConfig, SmtpTestResult } from "./types";
+/**
+ * Resource for managing listmonk server settings.
+ *
+ * Provides methods for reading and updating server configuration,
+ * as well as testing SMTP settings.
+ *
+ * @example
+ * ```typescript
+ * // Get all settings
+ * const settings = await client.settings.get();
+ *
+ * // Update settings
+ * const result = await client.settings.update({
+ *   'app.site_name': 'My Newsletter',
+ *   ...settings,
+ * });
+ * ```
+ */
+export declare class SettingsResource extends APIResource {
+    /**
+     * Retrieves all server settings.
+     *
+     * Note: Sensitive fields (passwords, API keys) are masked in the response.
+     *
+     * @returns Complete settings object
+     *
+     * @example
+     * ```typescript
+     * const settings = await client.settings.getAll();
+     * console.log(`Site name: ${settings['app.site_name']}`);
+     * console.log(`SMTP host: ${settings.smtp[0].host}`);
+     * console.log(`SMTP password: ${settings.smtp[0].password}`); // ••••••••
+     * ```
+     */
+    getAll(): Promise<Settings>;
+    /**
+     * Updates all server settings.
+     *
+     * Note: Empty password fields preserve existing database values.
+     * At least one enabled SMTP configuration is required.
+     *
+     * @param settings - Complete settings object with updates
+     * @returns Update result - `true` or `{ needs_restart: true }` if campaigns running
+     *
+     * @example
+     * ```typescript
+     * const settings = await client.settings.get();
+     * const result = await client.settings.update({
+     *   ...settings,
+     *   'app.site_name': 'Updated Newsletter',
+     * });
+     *
+     * if (result === true) {
+     *   console.log('Settings updated and applied');
+     * } else if (result.needs_restart) {
+     *   console.log('Settings updated, restart required');
+     * }
+     * ```
+     */
+    update(settings: Settings): Promise<SettingsUpdateResponse>;
+    /**
+     * Updates a single setting by key.
+     *
+     * @param key - Setting key (e.g., 'app.site_name')
+     * @param value - New value for the setting
+     * @returns `true` on success
+     *
+     * @example
+     * ```typescript
+     * await client.settings.updateByKey('app.site_name', 'New Site Name');
+     * ```
+     */
+    updateByKey(key: string, value: unknown): Promise<true>;
+    /**
+     * Tests SMTP configuration by sending a test email.
+     *
+     * @param config - SMTP configuration to test
+     * @returns Array of log lines from the SMTP test
+     * @throws {ListmonkApiError} On SMTP failure (with log output)
+     *
+     * @example
+     * ```typescript
+     * const logs = await client.settings.testSmtp({
+     *   host: 'smtp.example.com',
+     *   port: 587,
+     *   auth_protocol: 'login',
+     *   username: 'user',
+     *   password: 'secret',
+     *   tls_type: 'STARTTLS',
+     *   email: 'test@example.com',
+     * });
+     *
+     * for (const line of logs) {
+     *   console.log(line);
+     * }
+     * ```
+     */
+    testSmtp(config: SmtpTestConfig): Promise<SmtpTestResult>;
+}

package/dist/resources/settings/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TypeScript types for settings module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/settings/types
+ */
+import type { z } from "zod";
+import type { SmtpAuthProtocolSchema, TlsTypeSchema, UploadProviderSchema, CaptchaProviderSchema, ServerHealthSchema, ServerConfigSchema, SettingsSchema, SettingsUpdateResponseSchema, SmtpConfigSchema, MessengerConfigSchema, SmtpTestConfigSchema, SmtpTestResultSchema, SecurityCaptchaSchema, SecurityOidcSchema, BouncePostmarkSchema, BounceForwardEmailSchema, BounceBoxSchema } from "./schemas";
+/**
+ * SMTP authentication protocol.
+ */
+export type SmtpAuthProtocol = z.infer<typeof SmtpAuthProtocolSchema>;
+/**
+ * TLS configuration type.
+ */
+export type TlsType = z.infer<typeof TlsTypeSchema>;
+/**
+ * Upload provider type.
+ */
+export type UploadProvider = z.infer<typeof UploadProviderSchema>;
+/**
+ * CAPTCHA provider type.
+ */
+export type CaptchaProvider = z.infer<typeof CaptchaProviderSchema>;
+/**
+ * Server health check response.
+ */
+export type ServerHealth = z.infer<typeof ServerHealthSchema>;
+/**
+ * Server configuration response.
+ */
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+/**
+ * Complete settings object.
+ */
+export type Settings = z.infer<typeof SettingsSchema>;
+/**
+ * Response from settings update.
+ */
+export type SettingsUpdateResponse = z.infer<typeof SettingsUpdateResponseSchema>;
+/**
+ * SMTP server configuration.
+ */
+export type SmtpConfig = z.infer<typeof SmtpConfigSchema>;
+/**
+ * Messenger configuration.
+ */
+export type MessengerConfig = z.infer<typeof MessengerConfigSchema>;
+/**
+ * Security CAPTCHA configuration.
+ */
+export type SecurityCaptcha = z.infer<typeof SecurityCaptchaSchema>;
+/**
+ * Security OIDC configuration.
+ */
+export type SecurityOidc = z.infer<typeof SecurityOidcSchema>;
+/**
+ * Bounce Postmark configuration.
+ */
+export type BouncePostmark = z.infer<typeof BouncePostmarkSchema>;
+/**
+ * Bounce Forward Email configuration.
+ */
+export type BounceForwardEmail = z.infer<typeof BounceForwardEmailSchema>;
+/**
+ * Bounce mailbox configuration.
+ */
+export type BounceBox = z.infer<typeof BounceBoxSchema>;
+/**
+ * SMTP test configuration request (input type).
+ */
+export type SmtpTestConfig = z.input<typeof SmtpTestConfigSchema>;
+/**
+ * SMTP test result response.
+ */
+export type SmtpTestResult = z.infer<typeof SmtpTestResultSchema>;

package/dist/resources/subscribers/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Subscribers resource module.
+ *
+ * Provides complete subscriber lifecycle management for the listmonk API.
+ *
+ * @module resources/subscribers
+ */
+export { SubscribersResource } from "./subscribers";
+export type { Subscriber, SubscriberStatus, SubscriptionStatus, ListSubscription, BounceRecord, BounceType, BounceCampaign, SubscriberAttribs, CreateSubscriberRequest, UpdateSubscriberRequest, ListSubscribersOptions, ListSubscribersResponse, ModifyListsRequest, ModifyListsForListRequest, ModifyListsByQueryRequest, QueryOperationRequest, BulkOperationResponse, SubscriberExportResponse, SubscriberProfile, ExportSubscription, CampaignView, LinkClick, ListAction, } from "./types";
+export { SubscriberSchema, SubscriberStatusSchema, SubscriptionStatusSchema, ListSubscriptionSchema, BounceRecordSchema, BounceTypeSchema, BounceCampaignSchema, SubscriberAttribsSchema, CreateSubscriberRequestSchema, UpdateSubscriberRequestSchema, ListSubscribersOptionsSchema, ListSubscribersResponseSchema, ModifyListsRequestSchema, ModifyListsForListRequestSchema, ModifyListsByQueryRequestSchema, QueryOperationRequestSchema, BulkOperationResponseSchema, SubscriberExportResponseSchema, ListActionSchema, } from "./schemas";

package/dist/resources/subscribers/schemas.d.ts

@@ -0,0 +1,360 @@
+/**
+ * Zod schemas for subscriber-related requests and responses.
+ *
+ * @module resources/subscribers/schemas
+ */
+import { z } from "zod";
+/**
+ * Subscriber account-level status.
+ */
+export declare const SubscriberStatusSchema: z.ZodEnum<{
+    enabled: "enabled";
+    disabled: "disabled";
+    blocklisted: "blocklisted";
+}>;
+/**
+ * Subscription status for a specific list.
+ */
+export declare const SubscriptionStatusSchema: z.ZodEnum<{
+    confirmed: "confirmed";
+    unconfirmed: "unconfirmed";
+    unsubscribed: "unsubscribed";
+}>;
+/**
+ * Actions for list membership modification.
+ */
+export declare const ListActionSchema: z.ZodEnum<{
+    add: "add";
+    remove: "remove";
+    unsubscribe: "unsubscribe";
+}>;
+export { BounceTypeSchema } from "../../schemas";
+/**
+ * Custom subscriber attributes (flexible JSON object).
+ */
+export declare const SubscriberAttribsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export { BounceCampaignSchema } from "../../schemas";
+/**
+ * List subscription details within a subscriber.
+ */
+export declare const ListSubscriptionSchema: z.ZodObject<{
+    subscription_status: z.ZodEnum<{
+        confirmed: "confirmed";
+        unconfirmed: "unconfirmed";
+        unsubscribed: "unsubscribed";
+    }>;
+    id: z.ZodNumber;
+    uuid: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    tags: z.ZodArray<z.ZodString>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Complete subscriber entity.
+ */
+export declare const SubscriberSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    uuid: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        enabled: "enabled";
+        disabled: "disabled";
+        blocklisted: "blocklisted";
+    }>;
+    attribs: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    lists: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        subscription_status: z.ZodEnum<{
+            confirmed: "confirmed";
+            unconfirmed: "unconfirmed";
+            unsubscribed: "unsubscribed";
+        }>;
+        id: z.ZodNumber;
+        uuid: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        tags: z.ZodArray<z.ZodString>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>>>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Bounce record for email delivery failures.
+ */
+export declare const BounceRecordSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    type: z.ZodEnum<{
+        hard: "hard";
+        soft: "soft";
+    }>;
+    source: z.ZodString;
+    meta: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    created_at: z.ZodString;
+    email: z.ZodString;
+    subscriber_uuid: z.ZodString;
+    subscriber_id: z.ZodNumber;
+    campaign: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Request to create a new subscriber.
+ *
+ * Note: Status can only be 'enabled' or 'blocklisted' on creation.
+ * 'disabled' status must be set via update.
+ */
+export declare const CreateSubscriberRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        enabled: "enabled";
+        blocklisted: "blocklisted";
+    }>;
+    lists: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodNumber>>>;
+    attribs: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    preconfirm_subscriptions: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * Request to update an existing subscriber.
+ *
+ * Note: The lists array replaces existing memberships entirely.
+ */
+export declare const UpdateSubscriberRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        enabled: "enabled";
+        disabled: "disabled";
+        blocklisted: "blocklisted";
+    }>;
+    lists: z.ZodArray<z.ZodNumber>;
+    attribs: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    preconfirm_subscriptions: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * Options for listing subscribers.
+ */
+export declare const ListSubscribersOptionsSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    search: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    list_id: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    subscription_status: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        unconfirmed: "unconfirmed";
+        unsubscribed: "unsubscribed";
+    }>>;
+    order_by: z.ZodOptional<z.ZodEnum<{
+        name: "name";
+        created_at: "created_at";
+        updated_at: "updated_at";
+        status: "status";
+    }>>;
+    order: z.ZodOptional<z.ZodEnum<{
+        ASC: "ASC";
+        DESC: "DESC";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Request to modify list memberships for subscribers by ID.
+ *
+ * Note: `status` is required when action is 'add'.
+ */
+export declare const ModifyListsRequestSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodNumber>;
+    action: z.ZodEnum<{
+        add: "add";
+        remove: "remove";
+        unsubscribe: "unsubscribe";
+    }>;
+    target_list_ids: z.ZodArray<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        unconfirmed: "unconfirmed";
+        unsubscribed: "unsubscribed";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Request to modify list memberships for a specific list.
+ */
+export declare const ModifyListsForListRequestSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodNumber>;
+    action: z.ZodEnum<{
+        add: "add";
+        remove: "remove";
+        unsubscribe: "unsubscribe";
+    }>;
+    status: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        unconfirmed: "unconfirmed";
+        unsubscribed: "unsubscribed";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Request to modify list memberships by SQL-style query.
+ */
+export declare const ModifyListsByQueryRequestSchema: z.ZodObject<{
+    query: z.ZodString;
+    action: z.ZodEnum<{
+        add: "add";
+        remove: "remove";
+        unsubscribe: "unsubscribe";
+    }>;
+    target_list_ids: z.ZodArray<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        unconfirmed: "unconfirmed";
+        unsubscribed: "unsubscribed";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Request for query-based operations (delete, blocklist).
+ */
+export declare const QueryOperationRequestSchema: z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>;
+export { BulkDeleteIdsSchema } from "../../schemas";
+/**
+ * Schema for bulk blocklist by IDs.
+ */
+export declare const BulkBlocklistRequestSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Paginated list of subscribers response.
+ */
+export declare const ListSubscribersResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        uuid: z.ZodString;
+        email: z.ZodString;
+        name: z.ZodString;
+        status: z.ZodEnum<{
+            enabled: "enabled";
+            disabled: "disabled";
+            blocklisted: "blocklisted";
+        }>;
+        attribs: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        lists: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            subscription_status: z.ZodEnum<{
+                confirmed: "confirmed";
+                unconfirmed: "unconfirmed";
+                unsubscribed: "unsubscribed";
+            }>;
+            id: z.ZodNumber;
+            uuid: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                public: "public";
+                private: "private";
+            }>;
+            tags: z.ZodArray<z.ZodString>;
+            created_at: z.ZodString;
+            updated_at: z.ZodString;
+        }, z.core.$strip>>>>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    per_page: z.ZodNumber;
+    page: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Response for bulk operations.
+ */
+export declare const BulkOperationResponseSchema: z.ZodObject<{
+    count: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Subscriber profile in export.
+ */
+export declare const SubscriberProfileSchema: z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodString;
+    attribs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    status: z.ZodEnum<{
+        enabled: "enabled";
+        disabled: "disabled";
+        blocklisted: "blocklisted";
+    }>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Subscription in export (private list names masked).
+ */
+export declare const ExportSubscriptionSchema: z.ZodObject<{
+    name: z.ZodString;
+    subscription_status: z.ZodEnum<{
+        confirmed: "confirmed";
+        unconfirmed: "unconfirmed";
+        unsubscribed: "unsubscribed";
+    }>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Campaign view in export.
+ */
+export declare const CampaignViewSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    viewed_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Link click in export.
+ */
+export declare const LinkClickSchema: z.ZodObject<{
+    url: z.ZodString;
+    campaign_id: z.ZodNumber;
+    campaign_name: z.ZodString;
+    clicked_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Complete subscriber export response.
+ */
+export declare const SubscriberExportResponseSchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodString;
+        attribs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        status: z.ZodEnum<{
+            enabled: "enabled";
+            disabled: "disabled";
+            blocklisted: "blocklisted";
+        }>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>;
+    subscriptions: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        subscription_status: z.ZodEnum<{
+            confirmed: "confirmed";
+            unconfirmed: "unconfirmed";
+            unsubscribed: "unsubscribed";
+        }>;
+        created_at: z.ZodString;
+    }, z.core.$strip>>;
+    campaign_views: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+        viewed_at: z.ZodString;
+    }, z.core.$strip>>;
+    link_clicks: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        campaign_id: z.ZodNumber;
+        campaign_name: z.ZodString;
+        clicked_at: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;