@solytude/listmonk 1.0.0

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

@@ -0,0 +1,48 @@
+/**
+ * TypeScript types for media module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/media/types
+ */
+import type { z } from "zod";
+import type { MediaSchema, MediaUploadObjectSchema } from "./schemas";
+/**
+ * Complete media entity.
+ *
+ * Represents an uploaded media file (image, PDF, etc.) with metadata.
+ */
+export type Media = z.infer<typeof MediaSchema>;
+/**
+ * Node.js pattern for file upload: { filename, content }.
+ */
+export type MediaUploadObject = z.infer<typeof MediaUploadObjectSchema>;
+/**
+ * Input for media file upload.
+ *
+ * Supports:
+ * - Web API: File objects (filename extracted from file.name)
+ * - Node.js/Bun: Object with filename and Buffer/Uint8Array content
+ *
+ * NOTE: Plain Blob objects are NOT supported because they lack a filename.
+ * Use File (which extends Blob) or { filename, content } pattern instead.
+ *
+ * @example Browser (File API)
+ * ```typescript
+ * const file = new File([content], 'image.jpg', { type: 'image/jpeg' });
+ * await client.media.upload(file);
+ * ```
+ *
+ * @example Node.js (Buffer pattern)
+ * ```typescript
+ * await client.media.upload({
+ *   filename: 'image.jpg',
+ *   content: Buffer.from(imageData),
+ * });
+ * ```
+ */
+export type MediaUploadInput = File | {
+    filename: string;
+    content: Buffer | Uint8Array;
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Public resource module.
+ *
+ * Provides access to unauthenticated public endpoints for the listmonk API.
+ *
+ * @module resources/public
+ */
+export { PublicResource } from "./public";
+export type { CaptchaAlgorithm, PublicList, PublicSubscribeRequest, PublicSubscribeResponse, AltchaCaptchaChallenge, } from "./types";
+export { CaptchaAlgorithmSchema, PublicListSchema, PublicListsResponseSchema, PublicSubscribeRequestSchema, PublicSubscribeResponseSchema, AltchaCaptchaChallengeSchema, } from "./schemas";

package/dist/resources/public/public.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Public resource for unauthenticated endpoints.
+ *
+ * @module resources/public
+ */
+import { APIResource } from "../../http/resource";
+import type { PublicList, PublicSubscribeRequest, PublicSubscribeResponse, AltchaCaptchaChallenge } from "./types";
+/**
+ * Resource for public (unauthenticated) endpoints on listmonk.
+ *
+ * These endpoints don't require authentication and are intended
+ * for use in public subscription forms and similar scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Get public lists
+ * const lists = await client.public.getLists();
+ *
+ * // Submit subscription
+ * await client.public.subscribe({
+ *   email: 'user@example.com',
+ *   list_uuids: [lists[0].uuid],
+ * });
+ * ```
+ */
+export declare class PublicResource extends APIResource {
+    /**
+     * Makes an unauthenticated GET request.
+     */
+    private getPublic;
+    /**
+     * Makes an unauthenticated POST request.
+     */
+    private postPublic;
+    /**
+     * Retrieves public lists.
+     *
+     * Returns only lists marked as public, with minimal information
+     * (UUID and name) suitable for subscription forms.
+     *
+     * @returns Array of public lists
+     *
+     * @example
+     * ```typescript
+     * const lists = await client.public.getLists();
+     *
+     * for (const list of lists) {
+     *   console.log(`${list.name} (${list.uuid})`);
+     * }
+     * ```
+     */
+    getLists(): Promise<PublicList[]>;
+    /**
+     * Submits a public subscription request.
+     *
+     * Used for building custom subscription forms that integrate
+     * with listmonk's double opt-in workflow.
+     *
+     * @param request - Subscription request data
+     * @returns Response indicating opt-in status
+     * @throws {ListmonkApiError} On invalid email, CAPTCHA, or disabled subscriptions
+     *
+     * @example
+     * ```typescript
+     * // Simple subscription
+     * const result = await client.public.subscribe({
+     *   email: 'user@example.com',
+     *   list_uuids: ['550e8400-e29b-41d4-a716-446655440000'],
+     * });
+     *
+     * if (result.has_optin) {
+     *   console.log('Confirmation email sent (double opt-in)');
+     * } else {
+     *   console.log('Subscribed directly (single opt-in)');
+     * }
+     *
+     * // With name and CAPTCHA
+     * await client.public.subscribe({
+     *   email: 'user@example.com',
+     *   name: 'John Doe',
+     *   list_uuids: ['550e8400-e29b-41d4-a716-446655440000'],
+     *   altcha: 'base64EncodedCaptchaSolution',
+     * });
+     * ```
+     */
+    subscribe(request: PublicSubscribeRequest): Promise<PublicSubscribeResponse>;
+    /**
+     * Retrieves an Altcha CAPTCHA challenge.
+     *
+     * The challenge object should be passed to the Altcha widget
+     * on the client side for proof-of-work solving.
+     *
+     * @returns CAPTCHA challenge object
+     * @throws {ListmonkNotFoundError} If Altcha CAPTCHA is not enabled
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const challenge = await client.public.getCaptchaChallenge();
+     *   console.log(`Algorithm: ${challenge.algorithm}`);
+     *   console.log(`Max number: ${challenge.maxNumber}`);
+     *   // Pass to Altcha widget for solving
+     * } catch (error) {
+     *   if (error.status === 404) {
+     *     console.log('CAPTCHA not enabled on this server');
+     *   }
+     * }
+     * ```
+     */
+    getCaptchaChallenge(): Promise<AltchaCaptchaChallenge>;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Zod schemas for public endpoint requests and responses.
+ *
+ * @module resources/public/schemas
+ */
+import { z } from "zod";
+import { PublicListSchema } from "../lists/schemas";
+/**
+ * CAPTCHA algorithm for Altcha.
+ */
+export declare const CaptchaAlgorithmSchema: z.ZodEnum<{
+    "SHA-1": "SHA-1";
+    "SHA-256": "SHA-256";
+    "SHA-512": "SHA-512";
+}>;
+export { PublicListSchema };
+/**
+ * Public lists response (array of public lists).
+ */
+export declare const PublicListsResponseSchema: z.ZodArray<z.ZodObject<{
+    uuid: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>>;
+/**
+ * Public subscription request.
+ */
+export declare const PublicSubscribeRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    list_uuids: z.ZodArray<z.ZodString>;
+    altcha: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Public subscription response.
+ */
+export declare const PublicSubscribeResponseSchema: z.ZodObject<{
+    has_optin: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Altcha CAPTCHA challenge object.
+ */
+export declare const AltchaCaptchaChallengeSchema: z.ZodObject<{
+    algorithm: z.ZodEnum<{
+        "SHA-1": "SHA-1";
+        "SHA-256": "SHA-256";
+        "SHA-512": "SHA-512";
+    }>;
+    challenge: z.ZodString;
+    maxNumber: z.ZodNumber;
+    salt: z.ZodString;
+    signature: z.ZodString;
+}, z.core.$strip>;

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

@@ -0,0 +1,30 @@
+/**
+ * TypeScript types for public module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/public/types
+ */
+import type { z } from "zod";
+import type { CaptchaAlgorithmSchema, PublicListSchema, PublicSubscribeRequestSchema, PublicSubscribeResponseSchema, AltchaCaptchaChallengeSchema } from "./schemas";
+/**
+ * CAPTCHA algorithm for Altcha.
+ */
+export type CaptchaAlgorithm = z.infer<typeof CaptchaAlgorithmSchema>;
+/**
+ * Public list info (minimal fields for public forms).
+ */
+export type PublicList = z.infer<typeof PublicListSchema>;
+/**
+ * Public subscription request (input type).
+ */
+export type PublicSubscribeRequest = z.input<typeof PublicSubscribeRequestSchema>;
+/**
+ * Public subscription response.
+ */
+export type PublicSubscribeResponse = z.infer<typeof PublicSubscribeResponseSchema>;
+/**
+ * Altcha CAPTCHA challenge object.
+ */
+export type AltchaCaptchaChallenge = z.infer<typeof AltchaCaptchaChallengeSchema>;

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

@@ -0,0 +1,10 @@
+/**
+ * Settings resource module.
+ *
+ * Provides complete settings management for the listmonk API.
+ *
+ * @module resources/settings
+ */
+export { SettingsResource } from "./settings";
+export type { SmtpAuthProtocol, TlsType, UploadProvider, CaptchaProvider, ServerHealth, ServerConfig, Settings, SettingsUpdateResponse, SmtpConfig, MessengerConfig, SecurityCaptcha, SecurityOidc, BouncePostmark, BounceForwardEmail, BounceBox, SmtpTestConfig, SmtpTestResult, } from "./types";
+export { SmtpAuthProtocolSchema, TlsTypeSchema, UploadProviderSchema, CaptchaProviderSchema, ServerHealthSchema, ServerConfigSchema, SecurityCaptchaSchema, SecurityOidcSchema, SmtpConfigSchema, MessengerConfigSchema, BouncePostmarkSchema, BounceForwardEmailSchema, BounceBoxSchema, SettingsSchema, SettingsUpdateResponseSchema, SmtpTestConfigSchema, SmtpTestResultSchema, } from "./schemas";

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

@@ -0,0 +1,374 @@
+/**
+ * Zod schemas for settings-related requests and responses.
+ *
+ * @module resources/settings/schemas
+ */
+import { z } from "zod";
+/**
+ * SMTP authentication protocol.
+ */
+export declare const SmtpAuthProtocolSchema: z.ZodEnum<{
+    plain: "plain";
+    login: "login";
+    cram: "cram";
+    none: "none";
+}>;
+/**
+ * TLS configuration type.
+ */
+export declare const TlsTypeSchema: z.ZodEnum<{
+    none: "none";
+    STARTTLS: "STARTTLS";
+    TLS: "TLS";
+}>;
+/**
+ * Upload provider type.
+ */
+export declare const UploadProviderSchema: z.ZodEnum<{
+    filesystem: "filesystem";
+    s3: "s3";
+}>;
+/**
+ * CAPTCHA provider type.
+ */
+export declare const CaptchaProviderSchema: z.ZodNullable<z.ZodEnum<{
+    altcha: "altcha";
+    hcaptcha: "hcaptcha";
+}>>;
+/**
+ * Server health check response.
+ */
+export declare const ServerHealthSchema: z.ZodLiteral<true>;
+/**
+ * Server configuration response.
+ */
+export declare const ServerConfigSchema: z.ZodObject<{
+    root_url: z.ZodString;
+    from_email: z.ZodString;
+    lang: z.ZodString;
+    langs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        code: z.ZodString;
+    }, z.core.$strip>>;
+    public_subscription: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        captcha_enabled: z.ZodBoolean;
+        captcha_provider: z.ZodNullable<z.ZodEnum<{
+            altcha: "altcha";
+            hcaptcha: "hcaptcha";
+        }>>;
+        captcha_key: z.ZodNullable<z.ZodString>;
+        altcha_complexity: z.ZodNumber;
+    }, z.core.$strip>;
+    media_provider: z.ZodEnum<{
+        filesystem: "filesystem";
+        s3: "s3";
+    }>;
+    messengers: z.ZodArray<z.ZodString>;
+    permissions: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    update: z.ZodNullable<z.ZodObject<{
+        release_version: z.ZodString;
+        release_date: z.ZodString;
+        url: z.ZodString;
+        description: z.ZodString;
+        is_new: z.ZodBoolean;
+    }, z.core.$strip>>;
+    needs_restart: z.ZodBoolean;
+    has_legacy_user: z.ZodBoolean;
+    version: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Security CAPTCHA configuration.
+ */
+export declare const SecurityCaptchaSchema: z.ZodObject<{
+    altcha: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        complexity: z.ZodNumber;
+    }, z.core.$strip>;
+    hcaptcha: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        key: z.ZodString;
+        secret: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Security OIDC configuration.
+ */
+export declare const SecurityOidcSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    provider_url: z.ZodString;
+    provider_name: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodString;
+    auto_create_users: z.ZodBoolean;
+    default_user_role_id: z.ZodNullable<z.ZodNumber>;
+    default_list_role_id: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * SMTP server configuration.
+ */
+export declare const SmtpConfigSchema: z.ZodObject<{
+    uuid: z.ZodString;
+    enabled: z.ZodBoolean;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    hello_hostname: z.ZodOptional<z.ZodString>;
+    auth_protocol: z.ZodEnum<{
+        plain: "plain";
+        login: "login";
+        cram: "cram";
+        none: "none";
+    }>;
+    username: z.ZodString;
+    password: z.ZodString;
+    email_headers: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    max_conns: z.ZodNumber;
+    max_msg_retries: z.ZodNumber;
+    idle_timeout: z.ZodString;
+    wait_timeout: z.ZodString;
+    tls_type: z.ZodEnum<{
+        none: "none";
+        STARTTLS: "STARTTLS";
+        TLS: "TLS";
+    }>;
+    tls_skip_verify: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Messenger configuration.
+ */
+export declare const MessengerConfigSchema: z.ZodObject<{
+    uuid: z.ZodString;
+    enabled: z.ZodBoolean;
+    name: z.ZodString;
+    root_url: z.ZodString;
+    username: z.ZodString;
+    password: z.ZodString;
+    max_conns: z.ZodNumber;
+    timeout: z.ZodString;
+    max_msg_retries: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Bounce Postmark configuration.
+ */
+export declare const BouncePostmarkSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    username: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Bounce Forward Email configuration.
+ */
+export declare const BounceForwardEmailSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    key: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Bounce mailbox configuration.
+ */
+export declare const BounceBoxSchema: z.ZodObject<{
+    uuid: z.ZodString;
+    enabled: z.ZodBoolean;
+    type: z.ZodEnum<{
+        pop: "pop";
+        imap: "imap";
+    }>;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    auth_protocol: z.ZodString;
+    return_path: z.ZodString;
+    username: z.ZodString;
+    password: z.ZodString;
+    tls_type: z.ZodEnum<{
+        none: "none";
+        STARTTLS: "STARTTLS";
+        TLS: "TLS";
+    }>;
+    tls_skip_verify: z.ZodBoolean;
+    scan_interval: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Complete settings object with passthrough for forward compatibility.
+ */
+export declare const SettingsSchema: z.ZodObject<{
+    "app.site_name": z.ZodString;
+    "app.root_url": z.ZodString;
+    "app.logo_url": z.ZodString;
+    "app.favicon_url": z.ZodString;
+    "app.from_email": z.ZodString;
+    "app.notify_emails": z.ZodArray<z.ZodString>;
+    "app.lang": z.ZodString;
+    "app.enable_public_sub_page": z.ZodBoolean;
+    "app.enable_public_archive": z.ZodBoolean;
+    "app.enable_public_archive_rss_content": z.ZodBoolean;
+    "app.send_optin_confirmation": z.ZodBoolean;
+    "app.check_updates": z.ZodBoolean;
+    "app.batch_size": z.ZodNumber;
+    "app.concurrency": z.ZodNumber;
+    "app.max_send_errors": z.ZodNumber;
+    "app.message_rate": z.ZodNumber;
+    "app.message_sliding_window": z.ZodBoolean;
+    "app.message_sliding_window_duration": z.ZodString;
+    "app.message_sliding_window_rate": z.ZodNumber;
+    "app.cache_slow_queries": z.ZodBoolean;
+    "app.cache_slow_queries_interval": z.ZodString;
+    "privacy.individual_tracking": z.ZodBoolean;
+    "privacy.unsubscribe_header": z.ZodBoolean;
+    "privacy.allow_blocklist": z.ZodBoolean;
+    "privacy.allow_preferences": z.ZodBoolean;
+    "privacy.allow_export": z.ZodBoolean;
+    "privacy.allow_wipe": z.ZodBoolean;
+    "privacy.exportable": z.ZodArray<z.ZodString>;
+    "privacy.record_optin_ip": z.ZodBoolean;
+    "privacy.domain_blocklist": z.ZodArray<z.ZodString>;
+    "privacy.domain_allowlist": z.ZodArray<z.ZodString>;
+    "security.captcha": z.ZodObject<{
+        altcha: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            complexity: z.ZodNumber;
+        }, z.core.$strip>;
+        hcaptcha: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            key: z.ZodString;
+            secret: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    "security.oidc": z.ZodObject<{
+        enabled: z.ZodBoolean;
+        provider_url: z.ZodString;
+        provider_name: z.ZodString;
+        client_id: z.ZodString;
+        client_secret: z.ZodString;
+        auto_create_users: z.ZodBoolean;
+        default_user_role_id: z.ZodNullable<z.ZodNumber>;
+        default_list_role_id: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    "security.cors_origins": z.ZodArray<z.ZodString>;
+    "upload.provider": z.ZodEnum<{
+        filesystem: "filesystem";
+        s3: "s3";
+    }>;
+    "upload.extensions": z.ZodArray<z.ZodString>;
+    "upload.filesystem.upload_path": z.ZodString;
+    "upload.filesystem.upload_uri": z.ZodString;
+    "upload.s3.url": z.ZodString;
+    "upload.s3.public_url": z.ZodString;
+    "upload.s3.aws_access_key_id": z.ZodString;
+    "upload.s3.aws_secret_access_key": z.ZodString;
+    "upload.s3.aws_default_region": z.ZodString;
+    "upload.s3.bucket": z.ZodString;
+    "upload.s3.bucket_domain": z.ZodString;
+    "upload.s3.bucket_path": z.ZodString;
+    "upload.s3.bucket_type": z.ZodString;
+    "upload.s3.expiry": z.ZodString;
+    smtp: z.ZodArray<z.ZodObject<{
+        uuid: z.ZodString;
+        enabled: z.ZodBoolean;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        hello_hostname: z.ZodOptional<z.ZodString>;
+        auth_protocol: z.ZodEnum<{
+            plain: "plain";
+            login: "login";
+            cram: "cram";
+            none: "none";
+        }>;
+        username: z.ZodString;
+        password: z.ZodString;
+        email_headers: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        max_conns: z.ZodNumber;
+        max_msg_retries: z.ZodNumber;
+        idle_timeout: z.ZodString;
+        wait_timeout: z.ZodString;
+        tls_type: z.ZodEnum<{
+            none: "none";
+            STARTTLS: "STARTTLS";
+            TLS: "TLS";
+        }>;
+        tls_skip_verify: z.ZodBoolean;
+    }, z.core.$strip>>;
+    messengers: z.ZodArray<z.ZodObject<{
+        uuid: z.ZodString;
+        enabled: z.ZodBoolean;
+        name: z.ZodString;
+        root_url: z.ZodString;
+        username: z.ZodString;
+        password: z.ZodString;
+        max_conns: z.ZodNumber;
+        timeout: z.ZodString;
+        max_msg_retries: z.ZodNumber;
+    }, z.core.$strip>>;
+    "bounce.enabled": z.ZodBoolean;
+    "bounce.enable_webhooks": z.ZodBoolean;
+    "bounce.actions": z.ZodRecord<z.ZodString, z.ZodString>;
+    "bounce.ses_enabled": z.ZodBoolean;
+    "bounce.sendgrid_enabled": z.ZodBoolean;
+    "bounce.sendgrid_key": z.ZodString;
+    "bounce.postmark": z.ZodObject<{
+        enabled: z.ZodBoolean;
+        username: z.ZodString;
+        password: z.ZodString;
+    }, z.core.$strip>;
+    "bounce.forward_email": z.ZodObject<{
+        enabled: z.ZodBoolean;
+        key: z.ZodString;
+    }, z.core.$strip>;
+    "bounce.boxes": z.ZodArray<z.ZodObject<{
+        uuid: z.ZodString;
+        enabled: z.ZodBoolean;
+        type: z.ZodEnum<{
+            pop: "pop";
+            imap: "imap";
+        }>;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        auth_protocol: z.ZodString;
+        return_path: z.ZodString;
+        username: z.ZodString;
+        password: z.ZodString;
+        tls_type: z.ZodEnum<{
+            none: "none";
+            STARTTLS: "STARTTLS";
+            TLS: "TLS";
+        }>;
+        tls_skip_verify: z.ZodBoolean;
+        scan_interval: z.ZodString;
+    }, z.core.$strip>>;
+    "appearance.admin.custom_css": z.ZodString;
+    "appearance.admin.custom_js": z.ZodString;
+    "appearance.public.custom_css": z.ZodString;
+    "appearance.public.custom_js": z.ZodString;
+}, z.core.$loose>;
+/**
+ * Response from settings update.
+ * Can be either `true` or `{ needs_restart: true }` when campaigns are running.
+ */
+export declare const SettingsUpdateResponseSchema: z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+    needs_restart: z.ZodLiteral<true>;
+}, z.core.$strip>]>;
+/**
+ * SMTP test configuration request.
+ */
+export declare const SmtpTestConfigSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodNumber;
+    hello_hostname: z.ZodOptional<z.ZodString>;
+    auth_protocol: z.ZodEnum<{
+        plain: "plain";
+        login: "login";
+        cram: "cram";
+        none: "none";
+    }>;
+    username: z.ZodString;
+    password: z.ZodString;
+    tls_type: z.ZodEnum<{
+        none: "none";
+        STARTTLS: "STARTTLS";
+        TLS: "TLS";
+    }>;
+    tls_skip_verify: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    email: z.ZodString;
+}, z.core.$strip>;
+/**
+ * SMTP test result response (array of log lines).
+ */
+export declare const SmtpTestResultSchema: z.ZodArray<z.ZodString>;