@solytude/listmonk 1.0.0

package/dist/resources/admin/admin.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Admin resource for server administration.
+ *
+ * @module resources/admin
+ */
+import { APIResource } from "../../http/resource";
+import type { ReloadResponse, LogsResponse, SSEEvent, SSEStreamOptions } from "./types";
+/**
+ * Resource for administrative operations on the listmonk server.
+ *
+ * Provides methods for application reload, log retrieval, and
+ * real-time event streaming via SSE.
+ *
+ * @example
+ * ```typescript
+ * // Reload application
+ * await client.admin.reload();
+ *
+ * // Get logs
+ * const logs = await client.admin.getLogs();
+ * ```
+ */
+export declare class AdminResource extends APIResource {
+    /**
+     * Triggers an application reload.
+     *
+     * Sends a SIGHUP signal to the server after a 500ms delay
+     * for a graceful restart. The server may be briefly unavailable.
+     *
+     * @returns `true` on success
+     *
+     * @example
+     * ```typescript
+     * await client.admin.reload();
+     * console.log('Application reload triggered');
+     * // Note: Server may be briefly unavailable
+     * ```
+     */
+    reload(): Promise<ReloadResponse>;
+    /**
+     * Retrieves application logs.
+     *
+     * Returns up to 5000 most recent log lines.
+     *
+     * @returns Array of log lines
+     *
+     * @example
+     * ```typescript
+     * const logs = await client.admin.getLogs();
+     *
+     * // Print last 10 lines
+     * for (const line of logs.slice(-10)) {
+     *   console.log(line);
+     * }
+     * ```
+     */
+    getLogs(): Promise<LogsResponse>;
+    /**
+     * Opens a Server-Sent Events stream for real-time server events.
+     *
+     * Returns an async generator that yields events as they arrive.
+     * The stream stays open indefinitely until cancelled.
+     *
+     * Note: Listmonk's SSE does not support Last-Event-ID for reconnection.
+     * Events lost during disconnection cannot be recovered.
+     *
+     * @param options - Stream options
+     * @param options.signal - AbortSignal for cancellation
+     * @yields SSE events from the server
+     *
+     * @example
+     * ```typescript
+     * // Stop after 60 seconds using AbortSignal.timeout() (Node 17.3+)
+     * try {
+     *   for await (const event of client.admin.getEventStream({
+     *     signal: AbortSignal.timeout(60_000),
+     *   })) {
+     *     console.log(`Event: ${event.type}`);
+     *     console.log(`Message: ${event.message}`);
+     *     console.log(`Data:`, event.data);
+     *   }
+     * } catch (error) {
+     *   if (error.name === 'TimeoutError') {
+     *     console.log('Stream closed after timeout');
+     *   } else {
+     *     throw error;
+     *   }
+     * }
+     * ```
+     */
+    getEventStream(options?: SSEStreamOptions): AsyncGenerator<SSEEvent, void, undefined>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Admin resource module.
+ *
+ * Provides administrative operations for the listmonk API.
+ *
+ * @module resources/admin
+ */
+export { AdminResource } from "./admin";
+export type { ReloadResponse, LogsResponse, SSEEvent, SSEStreamOptions, } from "./types";
+export { ReloadResponseSchema, LogsResponseSchema, SSEEventSchema, } from "./schemas";

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

@@ -0,0 +1,23 @@
+/**
+ * Zod schemas for admin-related requests and responses.
+ *
+ * @module resources/admin/schemas
+ */
+import { z } from "zod";
+/**
+ * Application reload response.
+ */
+export declare const ReloadResponseSchema: z.ZodLiteral<true>;
+/**
+ * Application logs response (array of log lines).
+ */
+export declare const LogsResponseSchema: z.ZodArray<z.ZodString>;
+/**
+ * Server-sent event structure.
+ */
+export declare const SSEEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodString;
+    message: z.ZodString;
+    data: z.ZodUnknown;
+}, z.core.$strip>;

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

@@ -0,0 +1,29 @@
+/**
+ * TypeScript types for admin module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/admin/types
+ */
+import type { z } from "zod";
+import type { ReloadResponseSchema, LogsResponseSchema, SSEEventSchema } from "./schemas";
+/**
+ * Application reload response.
+ */
+export type ReloadResponse = z.infer<typeof ReloadResponseSchema>;
+/**
+ * Application logs response.
+ */
+export type LogsResponse = z.infer<typeof LogsResponseSchema>;
+/**
+ * Server-sent event structure.
+ */
+export type SSEEvent = z.infer<typeof SSEEventSchema>;
+/**
+ * Options for SSE event stream.
+ */
+export interface SSEStreamOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}

package/dist/resources/bounces/bounces.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Bounces resource for managing email bounce records.
+ *
+ * @module resources/bounces
+ */
+import { APIResource } from "../../http/resource";
+import type { Bounce, ListBouncesOptions, ListBouncesResponse } from "./types";
+import type { PagedAsyncIterableIterator } from "../../types/pagination";
+/**
+ * Resource for managing email bounce records in listmonk.
+ *
+ * Provides methods for listing, retrieving, and deleting bounce records,
+ * as well as blocklisting bounced subscribers.
+ *
+ * @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();
+ * ```
+ */
+export declare class BouncesResource extends APIResource {
+    /**
+     * Lists bounce records with optional filtering and pagination.
+     *
+     * Returns a paginated response containing bounce records. Use filtering
+     * options to narrow results by campaign or source.
+     *
+     * @param options - Query options for filtering and pagination
+     * @returns Paginated response with bounce records
+     *
+     * @example Basic listing
+     * ```typescript
+     * const response = await client.bounces.list();
+     * console.log(`Total bounces: ${response.total}`);
+     * for (const bounce of response.results) {
+     *   console.log(`${bounce.email}: ${bounce.type}`);
+     * }
+     * ```
+     *
+     * @example Filter by campaign
+     * ```typescript
+     * const campaignBounces = await client.bounces.list({
+     *   campaign_id: 5,
+     *   per_page: 100,
+     * });
+     * ```
+     *
+     * @example Filter by source with sorting
+     * ```typescript
+     * const sesBounces = await client.bounces.list({
+     *   source: 'ses',
+     *   order_by: 'created_at',
+     *   order: 'desc',
+     * });
+     * ```
+     *
+     * @example Pagination
+     * ```typescript
+     * const page2 = await client.bounces.list({
+     *   page: 2,
+     *   per_page: 25,
+     * });
+     * ```
+     */
+    list(options?: ListBouncesOptions): Promise<ListBouncesResponse>;
+    /**
+     * Returns an async iterator over all bounce records 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 bounce records
+     *
+     * @example Iterate over all bounces
+     * ```typescript
+     * for await (const bounce of client.bounces.listAll()) {
+     *   console.log(`Processing: ${bounce.email}`);
+     *   if (bounce.type === 'hard') {
+     *     // Handle hard bounces
+     *   }
+     * }
+     * ```
+     *
+     * @example Iterate by page
+     * ```typescript
+     * for await (const page of client.bounces.listAll().byPage()) {
+     *   console.log(`Page ${page.page}: ${page.results.length} bounces`);
+     * }
+     * ```
+     *
+     * @example With filtering
+     * ```typescript
+     * // All SES bounces, ordered by date
+     * for await (const bounce of client.bounces.listAll({
+     *   source: 'ses',
+     *   order_by: 'created_at',
+     *   order: 'desc',
+     * })) {
+     *   console.log(bounce.email, bounce.created_at);
+     * }
+     * ```
+     *
+     * @example Collect into array
+     * ```typescript
+     * const allBounces: Bounce[] = [];
+     * for await (const bounce of client.bounces.listAll()) {
+     *   allBounces.push(bounce);
+     * }
+     * ```
+     */
+    listAll(options?: Omit<ListBouncesOptions, "page">): PagedAsyncIterableIterator<Bounce, ListBouncesResponse>;
+    /**
+     * Deletes a single bounce record by ID.
+     *
+     * @param id - Bounce record ID
+     * @returns `true` on successful deletion
+     * @throws {ListmonkNotFoundError} If bounce record not found
+     * @throws {ListmonkValidationError} If ID is not a positive integer
+     *
+     * @example
+     * ```typescript
+     * const deleted = await client.bounces.remove(123);
+     * console.log(`Deleted: ${deleted}`); // true
+     * ```
+     */
+    remove(id: number): Promise<boolean>;
+    /**
+     * Deletes multiple bounce records by ID.
+     *
+     * All specified bounce records are deleted in a single API call.
+     *
+     * @param ids - Array of bounce record IDs to delete
+     * @returns `true` on successful deletion
+     * @throws {ListmonkValidationError} If ids is empty or contains invalid values
+     *
+     * @example
+     * ```typescript
+     * const deleted = await client.bounces.deleteMany([1, 2, 3, 4, 5]);
+     * console.log(`Deleted: ${deleted}`); // true
+     * ```
+     *
+     * @example With IDs from listing
+     * ```typescript
+     * // Get old bounces
+     * const oldBounceIds: number[] = [];
+     * for await (const bounce of client.bounces.listAll()) {
+     *   const bounceDate = new Date(bounce.created_at);
+     *   if (bounceDate < cutoffDate) {
+     *     oldBounceIds.push(bounce.id);
+     *   }
+     * }
+     *
+     * // Delete in batches
+     * const batchSize = 100;
+     * for (let i = 0; i < oldBounceIds.length; i += batchSize) {
+     *   const batch = oldBounceIds.slice(i, i + batchSize);
+     *   await client.bounces.deleteMany(batch);
+     * }
+     * ```
+     */
+    deleteMany(ids: number[]): Promise<boolean>;
+    /**
+     * Deletes all bounce records.
+     *
+     * **Warning**: This operation cannot be undone. Use with caution.
+     *
+     * @returns `true` on successful deletion
+     *
+     * @example
+     * ```typescript
+     * // Delete all bounce records
+     * const deleted = await client.bounces.deleteAll();
+     * console.log(`All bounces deleted: ${deleted}`); // true
+     * ```
+     */
+    deleteAll(): Promise<boolean>;
+    /**
+     * Retrieves a single bounce record by ID.
+     *
+     * @param id - Bounce record ID
+     * @returns The bounce record
+     * @throws {ListmonkNotFoundError} If bounce record not found
+     * @throws {ListmonkValidationError} If ID is not a positive integer
+     *
+     * @example
+     * ```typescript
+     * const bounce = await client.bounces.retrieve(123);
+     *
+     * console.log(`Bounce ID: ${bounce.id}`);
+     * console.log(`Type: ${bounce.type}`);
+     * console.log(`Email: ${bounce.email}`);
+     * console.log(`Source: ${bounce.source}`);
+     * console.log(`Subscriber ID: ${bounce.subscriber_id}`);
+     *
+     * // Access provider-specific metadata
+     * if (bounce.meta) {
+     *   console.log('Metadata:', bounce.meta);
+     *   // AWS SES: bounce.meta.bounceType, bounce.meta.bounceSubType
+     * }
+     *
+     * // Check campaign association
+     * if (bounce.campaign) {
+     *   console.log(`Campaign: ${bounce.campaign.name}`);
+     * }
+     * ```
+     */
+    retrieve(id: number): Promise<Bounce>;
+    /**
+     * Blocklists all subscribers who have bounced.
+     *
+     * This operation adds all subscribers with any bounce record to the
+     * blocklist. It is an all-or-nothing operation with no filtering options.
+     *
+     * The operation is idempotent - running it multiple times has no
+     * additional effect if no new bounces have occurred.
+     *
+     * @returns `true` on successful operation
+     *
+     * @example
+     * ```typescript
+     * // Blocklist all bounced subscribers
+     * const success = await client.bounces.blocklistBounced();
+     * console.log(`Blocklisted: ${success}`); // true
+     * ```
+     *
+     * @example Maintenance workflow
+     * ```typescript
+     * // 1. Review bounces first
+     * const response = await client.bounces.list({
+     *   order_by: 'created_at',
+     *   order: 'desc',
+     *   per_page: 100,
+     * });
+     * console.log(`Found ${response.total} bounce records`);
+     *
+     * // 2. Blocklist all bounced subscribers
+     * await client.bounces.blocklistBounced();
+     *
+     * // 3. Optionally clean up bounce records
+     * await client.bounces.deleteAll();
+     * ```
+     */
+    blocklistBounced(): Promise<boolean>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Bounces resource module.
+ *
+ * Provides bounce record management for the listmonk API.
+ *
+ * @module resources/bounces
+ */
+export { BouncesResource } from "./bounces";
+export type { Bounce, BounceType, BounceCampaign, ListBouncesOptions, ListBouncesResponse, } from "./types";
+export { BounceSchema, BounceTypeSchema, BounceCampaignSchema, ListBouncesOptionsSchema, ListBouncesResponseSchema, BulkDeleteIdsSchema, PositiveIdSchema, DeleteResponseSchema, } from "./schemas";

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

@@ -0,0 +1,86 @@
+/**
+ * Zod schemas for bounce-related requests and responses.
+ *
+ * @module resources/bounces/schemas
+ */
+import { z } from "zod";
+export { BounceTypeSchema, BounceCampaignSchema } from "../../schemas";
+/**
+ * Complete bounce entity returned from API.
+ *
+ * Represents an email delivery failure record with metadata.
+ */
+export declare const BounceSchema: 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>;
+/**
+ * Valid fields for sorting bounce records.
+ */
+export declare const BounceOrderBySchema: z.ZodEnum<{
+    type: "type";
+    created_at: "created_at";
+    email: "email";
+    source: "source";
+    campaign_name: "campaign_name";
+}>;
+/**
+ * Query parameters for listing bounce records.
+ */
+export declare const ListBouncesOptionsSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    campaign_id: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodString>;
+    order_by: z.ZodOptional<z.ZodEnum<{
+        type: "type";
+        created_at: "created_at";
+        email: "email";
+        source: "source";
+        campaign_name: "campaign_name";
+    }>>;
+    order: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Paginated response for bounce listing.
+ */
+export declare const ListBouncesResponseSchema: z.ZodObject<{
+    results: z.ZodArray<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>>;
+    query: z.ZodString;
+    total: z.ZodNumber;
+    per_page: z.ZodNumber;
+    page: z.ZodNumber;
+}, z.core.$strip>;
+export { DeleteResponseSchema, BulkDeleteIdsSchema, PositiveIdSchema, } from "../../schemas";

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

@@ -0,0 +1,37 @@
+/**
+ * TypeScript types for bounces module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/bounces/types
+ */
+import type { z } from "zod";
+import type { BounceSchema, BounceTypeSchema, BounceCampaignSchema, ListBouncesOptionsSchema, ListBouncesResponseSchema } from "./schemas";
+/**
+ * Bounce type classification.
+ *
+ * - `hard`: Permanent delivery failure (invalid address, domain doesn't exist)
+ * - `soft`: Temporary delivery failure (mailbox full, server unavailable)
+ */
+export type BounceType = z.infer<typeof BounceTypeSchema>;
+/**
+ * Embedded campaign reference in a bounce record.
+ */
+export type BounceCampaign = z.infer<typeof BounceCampaignSchema>;
+/**
+ * Complete bounce entity.
+ *
+ * Represents an email delivery failure record with metadata.
+ */
+export type Bounce = z.infer<typeof BounceSchema>;
+/**
+ * Options for listing bounces (input).
+ *
+ * Uses z.input to allow optional fields to be omitted.
+ */
+export type ListBouncesOptions = z.input<typeof ListBouncesOptionsSchema>;
+/**
+ * Paginated bounce list response (output).
+ */
+export type ListBouncesResponse = z.infer<typeof ListBouncesResponseSchema>;