@solytude/listmonk 1.0.0

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

@@ -0,0 +1,176 @@
+/**
+ * Zod schemas for list-related requests and responses.
+ *
+ * @module resources/lists/schemas
+ */
+import { z } from "zod";
+/**
+ * List visibility type.
+ * - `public`: List can be shown on public subscription forms
+ * - `private`: List is internal only, not visible to subscribers
+ */
+export declare const ListTypeSchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
+}>;
+/**
+ * Opt-in confirmation mode.
+ * - `single`: Subscribers are added immediately without confirmation
+ * - `double`: Subscribers must confirm via email before being added
+ */
+export declare const ListOptinSchema: z.ZodEnum<{
+    single: "single";
+    double: "double";
+}>;
+/**
+ * List availability status.
+ * - `active`: List is fully operational and visible in selectors
+ * - `archived`: List is hidden from UI selectors but retains data
+ */
+export declare const ListStatusSchema: z.ZodEnum<{
+    active: "active";
+    archived: "archived";
+}>;
+/**
+ * Complete list entity returned from authenticated endpoints.
+ */
+export declare const ListSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    uuid: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    optin: z.ZodEnum<{
+        single: "single";
+        double: "double";
+    }>;
+    status: z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>;
+    tags: z.ZodArray<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    subscriber_count: z.ZodOptional<z.ZodNumber>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Minimal list entity returned from the public endpoint (no auth required).
+ * Used for public subscription forms.
+ */
+export declare const PublicListSchema: z.ZodObject<{
+    uuid: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Request to create a new list.
+ */
+export declare const CreateListRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    optin: z.ZodEnum<{
+        single: "single";
+        double: "double";
+    }>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>>;
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Request to update an existing list.
+ * All fields are optional for partial updates.
+ */
+export declare const UpdateListRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>>;
+    optin: z.ZodOptional<z.ZodEnum<{
+        single: "single";
+        double: "double";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Options for listing and filtering lists.
+ */
+export declare const ListListsOptionsSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>>;
+    type: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>>;
+    optin: z.ZodOptional<z.ZodEnum<{
+        single: "single";
+        double: "double";
+    }>>;
+    tag: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    minimal: z.ZodOptional<z.ZodBoolean>;
+    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";
+    }>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"all">]>>>;
+}, z.core.$strip>;
+/**
+ * Request for query-based bulk deletion.
+ */
+export declare const BulkDeleteByQueryRequestSchema: z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>;
+export { BulkDeleteIdsSchema } from "../../schemas";
+/**
+ * Paginated response from the list endpoint.
+ */
+export declare const ListListsResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        uuid: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        optin: z.ZodEnum<{
+            single: "single";
+            double: "double";
+        }>;
+        status: z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+        }>;
+        tags: z.ZodArray<z.ZodString>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        subscriber_count: z.ZodOptional<z.ZodNumber>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    per_page: z.ZodNumber;
+    page: z.ZodNumber;
+}, z.core.$strip>;

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

@@ -0,0 +1,56 @@
+/**
+ * TypeScript types for lists module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/lists/types
+ */
+import type { z } from "zod";
+import type { ListSchema, PublicListSchema, ListTypeSchema, ListOptinSchema, ListStatusSchema, CreateListRequestSchema, UpdateListRequestSchema, ListListsOptionsSchema, ListListsResponseSchema, BulkDeleteByQueryRequestSchema } from "./schemas";
+/**
+ * List visibility type.
+ * - `public`: List can be shown on public subscription forms
+ * - `private`: List is internal only, not visible to subscribers
+ */
+export type ListType = z.infer<typeof ListTypeSchema>;
+/**
+ * Opt-in confirmation mode.
+ * - `single`: Subscribers are added immediately without confirmation
+ * - `double`: Subscribers must confirm via email before being added
+ */
+export type ListOptin = z.infer<typeof ListOptinSchema>;
+/**
+ * List availability status.
+ * - `active`: List is fully operational and visible in selectors
+ * - `archived`: List is hidden from UI selectors but retains data
+ */
+export type ListStatus = z.infer<typeof ListStatusSchema>;
+/**
+ * Complete list entity.
+ */
+export type List = z.infer<typeof ListSchema>;
+/**
+ * Minimal list entity for public endpoint.
+ */
+export type PublicList = z.infer<typeof PublicListSchema>;
+/**
+ * Request to create a new list (input type).
+ */
+export type CreateListRequest = z.input<typeof CreateListRequestSchema>;
+/**
+ * Request to update an existing list (input type).
+ */
+export type UpdateListRequest = z.input<typeof UpdateListRequestSchema>;
+/**
+ * Options for listing lists (input type).
+ */
+export type ListListsOptions = z.input<typeof ListListsOptionsSchema>;
+/**
+ * Request for query-based bulk deletion (input type).
+ */
+export type BulkDeleteByQueryRequest = z.input<typeof BulkDeleteByQueryRequestSchema>;
+/**
+ * Paginated list of lists response.
+ */
+export type ListListsResponse = z.infer<typeof ListListsResponseSchema>;

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

@@ -0,0 +1,10 @@
+/**
+ * Maintenance resource module.
+ *
+ * Provides garbage collection and cleanup operations for the listmonk API.
+ *
+ * @module resources/maintenance
+ */
+export { MaintenanceResource } from "./maintenance";
+export type { SubscriberGcType, AnalyticsGcType, GcCountResult, GcAnalyticsResult, } from "./types";
+export { SubscriberGcTypeSchema, AnalyticsGcTypeSchema, GcCountResultSchema, GcAnalyticsResultSchema, Rfc3339DateSchema, } from "./schemas";

package/dist/resources/maintenance/maintenance.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Maintenance resource for cleanup operations.
+ *
+ * @module resources/maintenance
+ */
+import { APIResource } from "../../http/resource";
+import type { SubscriberGcType, AnalyticsGcType, GcCountResult, GcAnalyticsResult } from "./types";
+/**
+ * Resource for maintenance and cleanup operations on listmonk.
+ *
+ * Provides garbage collection methods for removing old data,
+ * blocklisted subscribers, orphan records, and analytics data.
+ *
+ * @example
+ * ```typescript
+ * // Delete blocklisted subscribers
+ * const result = await client.maintenance.gcSubscribers('blocklisted');
+ * console.log(`Deleted ${result.count} subscribers`);
+ * ```
+ */
+export declare class MaintenanceResource extends APIResource {
+    /**
+     * Deletes subscribers by type (garbage collection).
+     *
+     * @param type - Type of subscribers to delete
+     *   - `blocklisted`: Delete all blocklisted subscribers
+     *   - `orphan`: Delete subscribers not in any list
+     * @returns Result with count of deleted records
+     *
+     * @example
+     * ```typescript
+     * // Delete blocklisted subscribers
+     * const blocklisted = await client.maintenance.gcSubscribers('blocklisted');
+     * console.log(`Deleted ${blocklisted.count} blocklisted subscribers`);
+     *
+     * // Delete orphan subscribers
+     * const orphans = await client.maintenance.gcSubscribers('orphan');
+     * console.log(`Deleted ${orphans.count} orphan subscribers`);
+     * ```
+     */
+    gcSubscribers(type: SubscriberGcType): Promise<GcCountResult>;
+    /**
+     * Deletes unconfirmed subscriptions older than a given date.
+     *
+     * Removes subscription records that were never confirmed
+     * (double opt-in pending).
+     *
+     * @param beforeDate - RFC3339 timestamp (delete records older than this)
+     * @returns Result with count of deleted records
+     *
+     * @example
+     * ```typescript
+     * // Delete unconfirmed subscriptions older than 3 months
+     * const cutoffDate = new Date();
+     * cutoffDate.setMonth(cutoffDate.getMonth() - 3);
+     *
+     * const result = await client.maintenance.gcSubscriptions(
+     *   cutoffDate.toISOString()
+     * );
+     * console.log(`Deleted ${result.count} unconfirmed subscriptions`);
+     * ```
+     */
+    gcSubscriptions(beforeDate: string): Promise<GcCountResult>;
+    /**
+     * Deletes analytics data older than a given date.
+     *
+     * Note: Returns `true` on success, not a count.
+     *
+     * @param type - Type of analytics to delete
+     *   - `all`: Delete all analytics data
+     *   - `views`: Delete campaign view records only
+     *   - `clicks`: Delete link click records only
+     * @param beforeDate - RFC3339 timestamp (delete records older than this)
+     * @returns `true` on success
+     *
+     * @example
+     * ```typescript
+     * // Delete all analytics older than 1 year
+     * const cutoffDate = new Date();
+     * cutoffDate.setFullYear(cutoffDate.getFullYear() - 1);
+     *
+     * await client.maintenance.gcAnalytics('all', cutoffDate.toISOString());
+     *
+     * // Delete only view records
+     * await client.maintenance.gcAnalytics('views', cutoffDate.toISOString());
+     *
+     * // Delete only click records
+     * await client.maintenance.gcAnalytics('clicks', cutoffDate.toISOString());
+     * ```
+     */
+    gcAnalytics(type: AnalyticsGcType, beforeDate: string): Promise<GcAnalyticsResult>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Zod schemas for maintenance-related requests and responses.
+ *
+ * @module resources/maintenance/schemas
+ */
+import { z } from "zod";
+/**
+ * Subscriber garbage collection type.
+ */
+export declare const SubscriberGcTypeSchema: z.ZodEnum<{
+    blocklisted: "blocklisted";
+    orphan: "orphan";
+}>;
+/**
+ * Analytics garbage collection type.
+ */
+export declare const AnalyticsGcTypeSchema: z.ZodEnum<{
+    all: "all";
+    views: "views";
+    clicks: "clicks";
+}>;
+/**
+ * GC result with count of deleted records.
+ * Used by gcSubscribers and gcSubscriptions.
+ */
+export declare const GcCountResultSchema: z.ZodObject<{
+    count: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * GC result for analytics (returns true, not count).
+ */
+export declare const GcAnalyticsResultSchema: z.ZodLiteral<true>;
+/**
+ * RFC3339 date validation for maintenance operations.
+ */
+export declare const Rfc3339DateSchema: z.ZodString;

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

@@ -0,0 +1,31 @@
+/**
+ * TypeScript types for maintenance module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/maintenance/types
+ */
+import type { z } from "zod";
+import type { SubscriberGcTypeSchema, AnalyticsGcTypeSchema, GcCountResultSchema, GcAnalyticsResultSchema } from "./schemas";
+/**
+ * Subscriber garbage collection type.
+ * - `blocklisted`: Delete blocklisted subscribers
+ * - `orphan`: Delete subscribers not in any list
+ */
+export type SubscriberGcType = z.infer<typeof SubscriberGcTypeSchema>;
+/**
+ * Analytics garbage collection type.
+ * - `all`: Delete all analytics data
+ * - `views`: Delete campaign view records only
+ * - `clicks`: Delete link click records only
+ */
+export type AnalyticsGcType = z.infer<typeof AnalyticsGcTypeSchema>;
+/**
+ * GC result with count of deleted records.
+ */
+export type GcCountResult = z.infer<typeof GcCountResultSchema>;
+/**
+ * GC result for analytics (always true on success).
+ */
+export type GcAnalyticsResult = z.infer<typeof GcAnalyticsResultSchema>;

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

@@ -0,0 +1,10 @@
+/**
+ * Media resource module.
+ *
+ * Provides media file upload and management for the listmonk API.
+ *
+ * @module resources/media
+ */
+export { MediaResource } from "./media";
+export type { Media, MediaUploadInput, MediaUploadObject } from "./types";
+export { MediaSchema, MediaUploadObjectSchema, ListMediaResponseSchema, DeleteResponseSchema, } from "./schemas";

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

@@ -0,0 +1,198 @@
+/**
+ * Media resource for managing media files (images, PDFs, etc.).
+ *
+ * @module resources/media
+ */
+import { APIResource } from "../../http/resource";
+import type { Media, MediaUploadInput } from "./types";
+import type { PagedAsyncIterableIterator } from "../../types/pagination";
+/**
+ * Resource for managing media files in listmonk.
+ *
+ * Provides methods for uploading, listing, retrieving, and deleting
+ * media files (images, PDFs, etc.) for use as campaign assets.
+ *
+ * @example
+ * ```typescript
+ * // Upload a file (Browser)
+ * const file = new File([content], 'hero.jpg', { type: 'image/jpeg' });
+ * const media = await client.media.upload(file);
+ *
+ * // Upload a file (Node.js)
+ * const media = await client.media.upload({
+ *   filename: 'hero.jpg',
+ *   content: readFileSync('./hero.jpg'),
+ * });
+ *
+ * // Use in campaign
+ * const campaign = await client.campaigns.create({
+ *   name: 'Newsletter',
+ *   body: `<img src="${media.url}" />`,
+ *   // ...
+ * });
+ * ```
+ */
+export declare class MediaResource extends APIResource {
+    /**
+     * Uploads a media file.
+     *
+     * Supports two input patterns:
+     * - **Browser**: File objects (filename automatically extracted from file.name)
+     * - **Node.js/Bun**: Object with `{ filename, content }` where content is Buffer/Uint8Array
+     *
+     * @param input - File to upload (File object or { filename, content } object)
+     * @returns The uploaded media file metadata
+     * @throws {ListmonkValidationError} If input is invalid (plain Blob, empty file, missing filename)
+     * @throws {ListmonkApiError} If server rejects the upload (file too large, unsupported type)
+     *
+     * @example Browser (File API)
+     * ```typescript
+     * // From a file input element
+     * const file = fileInput.files[0];
+     * const media = await client.media.upload(file);
+     * console.log(`Uploaded: ${media.url}`);
+     * ```
+     *
+     * @example Node.js (Buffer pattern)
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     *
+     * const media = await client.media.upload({
+     *   filename: 'campaign-hero.jpg',
+     *   content: readFileSync('./hero.jpg'),
+     * });
+     * console.log(`Thumbnail: ${media.thumb_url}`);
+     * ```
+     *
+     * @example Programmatic file creation
+     * ```typescript
+     * const file = new File(
+     *   [JSON.stringify({ data: 'test' })],
+     *   'data.json',
+     *   { type: 'application/json' }
+     * );
+     * const media = await client.media.upload(file);
+     * ```
+     */
+    upload(input: MediaUploadInput): Promise<Media>;
+    /**
+     * Validates upload input.
+     *
+     * @internal
+     * @throws {ListmonkValidationError} If input is invalid
+     */
+    private validateUploadInput;
+    /**
+     * Extracts filename from input.
+     *
+     * @internal
+     * @param input - Upload input
+     * @returns Filename string
+     */
+    private getFilename;
+    /**
+     * Converts input to a Blob/File suitable for FormData.
+     *
+     * @internal
+     * @param input - Upload input
+     * @param filename - Filename to use
+     * @returns Blob or File for FormData
+     */
+    private toFormDataFile;
+    /**
+     * Lists all media files.
+     *
+     * Note: The listmonk media API returns all files at once without pagination.
+     *
+     * @returns Array of all media files
+     *
+     * @example
+     * ```typescript
+     * const allMedia = await client.media.list();
+     * console.log(`Total: ${allMedia.length} files`);
+     *
+     * // Filter by content type (client-side)
+     * const images = allMedia.filter(m => m.content_type.startsWith('image/'));
+     * ```
+     */
+    list(): Promise<Media[]>;
+    /**
+     * Returns an async iterator over all media files.
+     *
+     * Note: Since the media API doesn't support pagination, this
+     * iterator yields all files in a single batch. The `byPage()`
+     * method yields a single "page" containing all files.
+     *
+     * This method is provided for API consistency with other resources.
+     *
+     * @returns Async iterator over media files
+     *
+     * @example
+     * ```typescript
+     * // Iterate over all media
+     * for await (const file of client.media.listAll()) {
+     *   console.log(file.filename);
+     * }
+     *
+     * // Iterate by "page" (single page for media)
+     * for await (const batch of client.media.listAll().byPage()) {
+     *   console.log(`Files in batch: ${batch.length}`);
+     * }
+     * ```
+     */
+    listAll(): PagedAsyncIterableIterator<Media, Media[]>;
+    /**
+     * Retrieves a media file by ID.
+     *
+     * @param id - Media file ID
+     * @returns The media file metadata
+     * @throws {ListmonkNotFoundError} If media file not found
+     *
+     * @example
+     * ```typescript
+     * const media = await client.media.retrieve(42);
+     * console.log(`File: ${media.filename}`);
+     * console.log(`Type: ${media.content_type}`);
+     * console.log(`URL: ${media.url}`);
+     * console.log(`Metadata: ${JSON.stringify(media.meta)}`);
+     * ```
+     */
+    retrieve(id: number): Promise<Media>;
+    /**
+     * Deletes a media file by ID.
+     *
+     * Note: References to this media in campaigns/templates will become broken links.
+     *
+     * @param id - Media file ID
+     * @returns `true` on successful deletion (Gap 1: returns boolean, not void)
+     * @throws {ListmonkNotFoundError} If media file not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await client.media.remove(42);
+     * console.log(`Deleted: ${deleted}`); // true
+     * ```
+     */
+    remove(id: number): Promise<boolean>;
+    /**
+     * Deletes multiple media files by ID.
+     *
+     * Note: The listmonk API does not support bulk media deletion,
+     * so this method deletes files sequentially. If any deletion fails,
+     * the error is thrown immediately and remaining files are not deleted
+     * (fail-fast behavior per spec).
+     *
+     * @param ids - Media file IDs to delete
+     * @throws {ListmonkNotFoundError} If any media file not found (fail-fast)
+     *
+     * @example
+     * ```typescript
+     * // Delete multiple files
+     * await client.media.deleteMany([1, 2, 3]);
+     *
+     * // Empty array is a no-op (no API calls)
+     * await client.media.deleteMany([]);
+     * ```
+     */
+    deleteMany(ids: number[]): Promise<void>;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Zod schemas for media-related requests and responses.
+ *
+ * @module resources/media/schemas
+ */
+import { z } from "zod";
+/**
+ * Complete media entity returned from API.
+ *
+ * Represents an uploaded media file (image, PDF, etc.) with metadata.
+ */
+export declare const MediaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    uuid: z.ZodString;
+    filename: z.ZodString;
+    created_at: z.ZodString;
+    thumb_url: z.ZodNullable<z.ZodString>;
+    url: z.ZodString;
+    content_type: z.ZodString;
+    provider: z.ZodString;
+    meta: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Schema for validating Node.js { filename, content } upload pattern.
+ *
+ * @internal
+ */
+export declare const MediaUploadObjectSchema: z.ZodObject<{
+    filename: z.ZodString;
+    content: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+/**
+ * Response for listing all media files.
+ * Note: Unlike paginated endpoints, media returns a simple array.
+ * The HttpClient automatically unwraps { data: [...] }.
+ */
+export declare const ListMediaResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    uuid: z.ZodString;
+    filename: z.ZodString;
+    created_at: z.ZodString;
+    thumb_url: z.ZodNullable<z.ZodString>;
+    url: z.ZodString;
+    content_type: z.ZodString;
+    provider: z.ZodString;
+    meta: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>>;
+export { DeleteResponseSchema } from "../../schemas";