@solytude/listmonk 1.0.0

package/dist/resources/import/import.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Import resource for bulk subscriber import from CSV/ZIP files.
+ *
+ * @module resources/import
+ */
+import { APIResource } from "../../http/resource";
+import type { ImportFileInput, ImportOptions, ImportConfig, ImportStatus } from "./types";
+/**
+ * Resource for bulk subscriber import in listmonk.
+ *
+ * Provides methods for uploading CSV/ZIP files and managing import jobs.
+ *
+ * @example
+ * ```typescript
+ * // Start import (Browser)
+ * const file = new File([csvContent], 'subscribers.csv');
+ * const config = await client.import.start(file, {
+ *   mode: 'subscribe',
+ *   delimiter: ',',
+ *   lists: [1, 2],
+ * });
+ *
+ * // Start import (Node.js)
+ * const config = 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();
+ * console.log(logs);
+ *
+ * // Cancel if needed
+ * await client.import.cancel();
+ * ```
+ */
+export declare class ImportResource extends APIResource {
+    /**
+     * Starts a bulk subscriber import from a CSV or ZIP 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 file - File to import (File object or { filename, content } object)
+     * @param options - Import configuration options
+     * @returns The import configuration as echoed by the server
+     * @throws {ListmonkValidationError} If input is invalid (plain Blob, empty file, missing filename, invalid extension)
+     * @throws {ListmonkApiError} If server rejects the request (invalid lists, malformed CSV)
+     *
+     * @example Browser (File API)
+     * ```typescript
+     * // From a file input element
+     * const file = fileInput.files[0];
+     * const config = await client.import.start(file, {
+     *   mode: 'subscribe',
+     *   delimiter: ',',
+     *   lists: [1, 2],
+     * });
+     * console.log(`Import started in ${config.mode} mode`);
+     * ```
+     *
+     * @example Node.js (Buffer pattern)
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     *
+     * const config = await client.import.start(
+     *   { filename: 'subscribers.csv', content: readFileSync('./subscribers.csv') },
+     *   {
+     *     mode: 'subscribe',
+     *     delimiter: ',',
+     *     lists: [1],
+     *     overwrite: true,
+     *     subscriptionStatus: 'confirmed',
+     *   }
+     * );
+     * ```
+     *
+     * @example Blocklist mode
+     * ```typescript
+     * await client.import.start(file, {
+     *   mode: 'blocklist',
+     *   delimiter: ',',
+     * });
+     * ```
+     */
+    start(file: ImportFileInput, options: ImportOptions): Promise<ImportConfig>;
+    /**
+     * Gets the current import status.
+     *
+     * Use this method to poll for import progress and detect completion.
+     *
+     * @returns The current import status
+     *
+     * @example Basic status check
+     * ```typescript
+     * const status = await client.import.getStatus();
+     * console.log(`Status: ${status.status}`);
+     * console.log(`Progress: ${status.imported}/${status.total}`);
+     * ```
+     *
+     * @example Polling for completion
+     * ```typescript
+     * await client.import.start(file, options);
+     *
+     * let status = await client.import.getStatus();
+     * while (status.status === 'processing' || status.status === 'importing') {
+     *   const percent = status.total > 0
+     *     ? Math.round((status.imported / status.total) * 100)
+     *     : 0;
+     *   console.log(`Progress: ${percent}%`);
+     *
+     *   await new Promise(r => setTimeout(r, 2000));
+     *   status = await client.import.getStatus();
+     * }
+     *
+     * console.log(`Finished: ${status.imported} records imported`);
+     * ```
+     */
+    getStatus(): Promise<ImportStatus>;
+    /**
+     * Gets the import logs.
+     *
+     * Logs are parsed from the raw newline-separated string into an array
+     * of log entries for easier processing.
+     *
+     * @returns Array of log entry strings
+     *
+     * @example
+     * ```typescript
+     * const logs = await client.import.getLogs();
+     *
+     * for (const entry of logs) {
+     *   console.log(entry);
+     * }
+     * // Output:
+     * // 2024-01-15 10:30:00 Starting import of subscribers.csv
+     * // 2024-01-15 10:30:01 Processing 1000 records
+     * // 2024-01-15 10:30:05 Row 523: Invalid email format skipped
+     * // 2024-01-15 10:30:15 Import completed: 999 imported, 1 skipped
+     * ```
+     *
+     * @example Filter for errors
+     * ```typescript
+     * const logs = await client.import.getLogs();
+     * const errors = logs.filter(line =>
+     *   line.toLowerCase().includes('error') ||
+     *   line.toLowerCase().includes('skipped')
+     * );
+     * console.log('Issues:', errors);
+     * ```
+     */
+    getLogs(): Promise<string[]>;
+    /**
+     * Cancels the active import.
+     *
+     * This operation is idempotent - calling it when no import is running
+     * will not throw an error.
+     *
+     * @returns `true` if an import was cancelled or no import was running
+     *
+     * @example
+     * ```typescript
+     * // Cancel active import
+     * const cancelled = await client.import.cancel();
+     * console.log('Cancelled:', cancelled); // true
+     * ```
+     *
+     * @example Idempotent behavior
+     * ```typescript
+     * // Safe to call even if no import is running
+     * await client.import.cancel(); // No error
+     * ```
+     */
+    cancel(): Promise<boolean>;
+    /**
+     * Validates file input.
+     *
+     * @internal
+     * @throws {ListmonkValidationError} If input is invalid
+     */
+    private validateFileInput;
+    /**
+     * 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;
+    /**
+     * Maps SDK options to API params format.
+     *
+     * @internal
+     * @param options - SDK options (camelCase)
+     * @returns API params (snake_case where needed)
+     */
+    private buildParams;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Import resource module.
+ *
+ * Provides bulk subscriber import from CSV/ZIP files for the listmonk API.
+ *
+ * @module resources/import
+ */
+export { ImportResource } from "./import";
+export type { ImportMode, ImportOptions, ImportParams, ImportStatus, ImportConfig, ImportFileInput, ImportFileObject, } from "./types";
+export { ImportModeSchema, ImportOptionsSchema, ImportParamsSchema, ImportStatusSchema, ImportConfigSchema, ImportFileObjectSchema, ImportLogsResponseSchema, DeleteImportResponseSchema, parseImportLogs, } from "./schemas";

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

@@ -0,0 +1,109 @@
+/**
+ * Zod schemas for import-related requests and responses.
+ *
+ * @module resources/import/schemas
+ */
+import { z } from "zod";
+/**
+ * Import mode controlling import behavior.
+ *
+ * - `subscribe`: Add subscribers to specified lists
+ * - `blocklist`: Add email addresses to blocklist
+ */
+export declare const ImportModeSchema: z.ZodEnum<{
+    subscribe: "subscribe";
+    blocklist: "blocklist";
+}>;
+/**
+ * SDK-facing configuration for starting an import.
+ *
+ * Uses camelCase per TypeScript conventions. Mapped to API format internally.
+ */
+export declare const ImportOptionsSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        subscribe: "subscribe";
+        blocklist: "blocklist";
+    }>;
+    delimiter: z.ZodString;
+    lists: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    overwrite: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    subscriptionStatus: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Object pattern for file input in Node.js.
+ *
+ * @internal
+ */
+export declare const ImportFileObjectSchema: z.ZodObject<{
+    filename: z.ZodString;
+    content: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+/**
+ * API request params field format (snake_case).
+ *
+ * @internal
+ */
+export declare const ImportParamsSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        subscribe: "subscribe";
+        blocklist: "blocklist";
+    }>;
+    delim: z.ZodString;
+    lists: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+    subscription_status: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Current state of an import operation.
+ */
+export declare const ImportStatusSchema: z.ZodObject<{
+    name: z.ZodString;
+    total: z.ZodNumber;
+    imported: z.ZodNumber;
+    status: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Configuration echo returned from successful import start.
+ *
+ * Note: This is the direct API response from POST, not wrapped in { data: ... }.
+ */
+export declare const ImportConfigSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        subscribe: "subscribe";
+        blocklist: "blocklist";
+    }>;
+    delim: z.ZodString;
+    lists: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Response from cancel operation.
+ *
+ * The API may return `true` or the status object after cancellation.
+ */
+export declare const DeleteImportResponseSchema: z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+    name: z.ZodString;
+    total: z.ZodNumber;
+    imported: z.ZodNumber;
+    status: z.ZodString;
+}, z.core.$strip>]>;
+/**
+ * Raw API response for logs endpoint.
+ *
+ * Logs are returned as a single string with newline separators.
+ */
+export declare const ImportLogsResponseSchema: z.ZodString;
+/**
+ * Parses raw log string from API into an array of log entries.
+ *
+ * @param raw - Raw log string from API (newline-separated)
+ * @returns Array of log entry strings
+ *
+ * @example
+ * ```typescript
+ * const raw = "2024-01-15 10:30:00 Started\n2024-01-15 10:30:01 Finished\n";
+ * const logs = parseImportLogs(raw);
+ * // logs = ["2024-01-15 10:30:00 Started", "2024-01-15 10:30:01 Finished"]
+ * ```
+ */
+export declare function parseImportLogs(raw: string): string[];

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

@@ -0,0 +1,72 @@
+/**
+ * TypeScript types for import module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/import/types
+ */
+import type { z } from "zod";
+import type { ImportModeSchema, ImportOptionsSchema, ImportParamsSchema, ImportStatusSchema, ImportConfigSchema, ImportFileObjectSchema } from "./schemas";
+/**
+ * Import mode enum type.
+ *
+ * - `"subscribe"`: Add subscribers to specified lists
+ * - `"blocklist"`: Add email addresses to blocklist
+ */
+export type ImportMode = z.infer<typeof ImportModeSchema>;
+/**
+ * SDK-facing import options (input type for API consumers).
+ *
+ * Uses camelCase per TypeScript conventions. `overwrite` is optional
+ * and defaults to `false` when not provided.
+ */
+export type ImportOptions = z.input<typeof ImportOptionsSchema>;
+/**
+ * API wire format for import params (snake_case).
+ *
+ * @internal
+ */
+export type ImportParams = z.infer<typeof ImportParamsSchema>;
+/**
+ * Current state of an import operation.
+ */
+export type ImportStatus = z.infer<typeof ImportStatusSchema>;
+/**
+ * Configuration echo returned from successful import start.
+ */
+export type ImportConfig = z.infer<typeof ImportConfigSchema>;
+/**
+ * Node.js pattern for file upload: { filename, content }.
+ */
+export type ImportFileObject = z.infer<typeof ImportFileObjectSchema>;
+/**
+ * Input for import 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([csvContent], 'subscribers.csv', { type: 'text/csv' });
+ * await client.import.start(file, options);
+ * ```
+ *
+ * @example Node.js (Buffer pattern)
+ * ```typescript
+ * import { readFileSync } from 'fs';
+ *
+ * await client.import.start({
+ *   filename: 'subscribers.csv',
+ *   content: readFileSync('./subscribers.csv'),
+ * }, options);
+ * ```
+ */
+export type ImportFileInput = File | {
+    filename: string;
+    content: Buffer | Uint8Array;
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Lists resource module.
+ *
+ * Provides complete mailing list management for the listmonk API.
+ *
+ * @module resources/lists
+ */
+export { ListsResource } from "./lists";
+export type { List, PublicList, ListType, ListOptin, ListStatus, CreateListRequest, UpdateListRequest, ListListsOptions, ListListsResponse, BulkDeleteByQueryRequest, } from "./types";
+export { ListSchema, PublicListSchema, ListTypeSchema, ListOptinSchema, ListStatusSchema, CreateListRequestSchema, UpdateListRequestSchema, ListListsOptionsSchema, ListListsResponseSchema, BulkDeleteByQueryRequestSchema, } from "./schemas";

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

@@ -0,0 +1,180 @@
+/**
+ * Lists resource for managing mailing lists.
+ *
+ * @module resources/lists
+ */
+import { APIResource } from "../../http/resource";
+import type { List, PublicList, CreateListRequest, UpdateListRequest, ListListsOptions, ListListsResponse } from "./types";
+import type { PagedAsyncIterableIterator } from "../../types/pagination";
+/**
+ * Resource for managing mailing lists in listmonk.
+ *
+ * Provides methods for CRUD operations, pagination, filtering,
+ * bulk deletion, and public lists access.
+ *
+ * @example
+ * ```typescript
+ * // Access via client
+ * const list = await client.lists.create({
+ *   name: 'Newsletter',
+ *   type: 'public',
+ *   optin: 'double',
+ * });
+ * ```
+ */
+export declare class ListsResource extends APIResource {
+    /**
+     * Creates a new mailing list.
+     *
+     * @param data - List data
+     * @returns The created list
+     *
+     * @example
+     * ```typescript
+     * const list = await client.lists.create({
+     *   name: 'Newsletter Subscribers',
+     *   type: 'public',
+     *   optin: 'double',
+     *   tags: ['newsletter', 'weekly'],
+     *   description: 'Weekly newsletter subscribers',
+     * });
+     * ```
+     */
+    create(data: CreateListRequest): Promise<List>;
+    /**
+     * Retrieves a list by ID.
+     *
+     * @param id - List ID
+     * @returns The list
+     * @throws {ListmonkNotFoundError} If list not found
+     *
+     * @example
+     * ```typescript
+     * const list = await client.lists.retrieve(1);
+     * console.log(list.name);
+     * ```
+     */
+    retrieve(id: number): Promise<List>;
+    /**
+     * Updates an existing list.
+     *
+     * All fields are optional - only provided fields are updated.
+     * Note: The `tags` array replaces existing tags entirely.
+     *
+     * @param id - List ID
+     * @param data - Updated list data
+     * @returns The updated list
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.lists.update(1, {
+     *   name: 'Weekly Newsletter',
+     *   status: 'active',
+     *   tags: ['newsletter', 'weekly', 'featured'],
+     * });
+     * ```
+     */
+    update(id: number, data: UpdateListRequest): Promise<List>;
+    /**
+     * Deletes a list by ID.
+     *
+     * Note: Deleting a list removes all subscriber associations
+     * (subscribers are unsubscribed from the list, not deleted).
+     *
+     * @param id - List ID
+     * @throws {ListmonkNotFoundError} If list not found
+     *
+     * @example
+     * ```typescript
+     * await client.lists.remove(1);
+     * ```
+     */
+    remove(id: number): Promise<void>;
+    /**
+     * Lists mailing lists with pagination and filtering.
+     *
+     * @param options - Query options
+     * @returns Paginated list response
+     *
+     * @example
+     * ```typescript
+     * const page = await client.lists.list({
+     *   page: 1,
+     *   per_page: 50,
+     *   status: 'active',
+     *   type: 'public',
+     *   order_by: 'created_at',
+     *   order: 'DESC',
+     * });
+     * ```
+     */
+    list(options?: ListListsOptions): Promise<ListListsResponse>;
+    /**
+     * Returns an async iterator over all lists matching the options.
+     *
+     * Pages are fetched on-demand as you iterate. The iterator also
+     * provides a `byPage()` method for page-level iteration.
+     *
+     * @param options - Query options (page is ignored, starts from 1)
+     * @returns Async iterator over lists
+     *
+     * @example
+     * ```typescript
+     * // Iterate over all lists
+     * for await (const list of client.lists.listAll()) {
+     *   console.log(list.name);
+     * }
+     *
+     * // Iterate over pages
+     * for await (const page of client.lists.listAll().byPage()) {
+     *   console.log(`Page ${page.page} has ${page.results.length} items`);
+     * }
+     * ```
+     */
+    listAll(options?: Omit<ListListsOptions, "page">): PagedAsyncIterableIterator<List, ListListsResponse>;
+    /**
+     * Deletes multiple lists by ID.
+     *
+     * Note: Lists the user doesn't have "manage" permission for
+     * are silently ignored (not an error).
+     *
+     * @param ids - List IDs to delete
+     *
+     * @example
+     * ```typescript
+     * await client.lists.deleteMany([1, 2, 3]);
+     * ```
+     */
+    deleteMany(ids: number[]): Promise<void>;
+    /**
+     * Deletes lists matching a SQL-style query.
+     *
+     * Note: Lists the user doesn't have "manage" permission for
+     * are silently ignored (not an error).
+     *
+     * @param query - SQL-style query expression
+     *
+     * @example
+     * ```typescript
+     * await client.lists.deleteByQuery("lists.status = 'archived'");
+     * ```
+     */
+    deleteByQuery(query: string): Promise<void>;
+    /**
+     * Retrieves public, active lists for subscription forms.
+     *
+     * This endpoint does NOT require authentication.
+     * Returns only `uuid` and `name` fields for security.
+     *
+     * @returns Array of public lists with minimal data
+     *
+     * @example
+     * ```typescript
+     * const publicLists = await client.lists.getPublic();
+     * for (const list of publicLists) {
+     *   console.log(`${list.name} (${list.uuid})`);
+     * }
+     * ```
+     */
+    getPublic(): Promise<PublicList[]>;
+}