@solytude/listmonk 1.0.0

package/dist/resources/campaigns/campaigns.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Campaigns resource for managing email campaigns.
+ *
+ * @module resources/campaigns
+ */
+import { APIResource } from "../../http/resource";
+import type { Campaign, CampaignStats, AnalyticsData, LinkAnalytics, AnalyticsType, CampaignContentType, CreateCampaignRequest, UpdateCampaignRequest, ListCampaignsOptions, ListCampaignsResponse, SendTestRequest, ArchiveRequest, GetAnalyticsOptions, PreviewResponse, PreviewOptions, CampaignStatus } from "./types";
+import type { PagedAsyncIterableIterator } from "../../types/pagination";
+/**
+ * Resource for managing email campaigns in listmonk.
+ *
+ * Provides methods for CRUD operations, status management, pagination,
+ * preview generation, analytics, test sending, and archive management.
+ *
+ * @example
+ * ```typescript
+ * // Access via client
+ * const campaign = await client.campaigns.create({
+ *   name: 'Weekly Newsletter',
+ *   subject: 'This Week in Tech',
+ *   lists: [1, 2],
+ *   body: '<h1>Hello!</h1>',
+ *   content_type: 'html',
+ * });
+ * ```
+ */
+export declare class CampaignsResource extends APIResource {
+    /**
+     * Creates a new campaign.
+     *
+     * The campaign is created in `draft` status and can be edited
+     * before starting or scheduling.
+     *
+     * @param data - Campaign data
+     * @returns The created campaign
+     *
+     * @example
+     * ```typescript
+     * const campaign = await client.campaigns.create({
+     *   name: 'Weekly Newsletter',
+     *   subject: 'This Week in Tech',
+     *   lists: [1, 2],
+     *   body: '<h1>Hello {{ .Subscriber.FirstName }}!</h1>',
+     *   content_type: 'html',
+     *   template_id: 1,
+     *   tags: ['newsletter', 'weekly'],
+     * });
+     * ```
+     */
+    create(data: CreateCampaignRequest): Promise<Campaign>;
+    /**
+     * Retrieves a campaign by ID.
+     *
+     * @param id - Campaign ID
+     * @param options - Optional query parameters
+     * @param options.no_body - Exclude body field from response
+     * @returns The campaign
+     * @throws {ListmonkNotFoundError} If campaign not found
+     *
+     * @example
+     * ```typescript
+     * const campaign = await client.campaigns.retrieve(123);
+     * console.log(campaign.name, campaign.status);
+     * ```
+     */
+    retrieve(id: number, options?: {
+        no_body?: boolean;
+    }): Promise<Campaign>;
+    /**
+     * Updates an existing campaign.
+     *
+     * All fields are optional - only provided fields are updated.
+     * Note: Only draft, scheduled, or paused campaigns can be fully updated.
+     * Running campaigns can only update tags and archive_meta.
+     *
+     * @param id - Campaign ID
+     * @param data - Updated campaign data
+     * @returns The updated campaign
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.campaigns.update(123, {
+     *   subject: 'Updated Subject Line',
+     *   tags: ['newsletter', 'updated'],
+     * });
+     * ```
+     */
+    update(id: number, data: UpdateCampaignRequest): Promise<Campaign>;
+    /**
+     * Deletes a campaign by ID.
+     *
+     * @param id - Campaign ID
+     * @throws {ListmonkNotFoundError} If campaign not found
+     *
+     * @example
+     * ```typescript
+     * await client.campaigns.remove(123);
+     * ```
+     */
+    remove(id: number): Promise<void>;
+    /**
+     * Lists campaigns with pagination and filtering.
+     *
+     * @param options - Query options
+     * @returns Paginated campaign response
+     *
+     * @example
+     * ```typescript
+     * const page = await client.campaigns.list({
+     *   status: ['running', 'scheduled'],
+     *   order_by: 'created_at',
+     *   order: 'DESC',
+     *   per_page: 50,
+     * });
+     * console.log(`Found ${page.total} campaigns`);
+     * ```
+     */
+    list(options?: ListCampaignsOptions): Promise<ListCampaignsResponse>;
+    /**
+     * Returns an async iterator over all campaigns 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 campaigns
+     *
+     * @example
+     * ```typescript
+     * // Iterate over all campaigns
+     * for await (const campaign of client.campaigns.listAll()) {
+     *   console.log(campaign.name, campaign.status);
+     * }
+     *
+     * // Iterate over pages
+     * for await (const page of client.campaigns.listAll().byPage()) {
+     *   console.log(`Page ${page.page} has ${page.results.length} items`);
+     * }
+     * ```
+     */
+    listAll(options?: Omit<ListCampaignsOptions, "page">): PagedAsyncIterableIterator<Campaign, ListCampaignsResponse>;
+    /**
+     * Changes the status of a campaign.
+     *
+     * Valid transitions:
+     * - `draft` -> `scheduled` (requires send_at), `running`
+     * - `scheduled` -> `draft`, `running`
+     * - `running` -> `paused`, `cancelled`
+     * - `paused` -> `running`
+     *
+     * @param id - Campaign ID
+     * @param status - Target status
+     * @param options - Additional options (send_at required for 'scheduled')
+     * @returns The updated campaign
+     *
+     * @example
+     * ```typescript
+     * // Start a campaign immediately
+     * await client.campaigns.updateStatus(123, 'running');
+     *
+     * // Schedule for later
+     * await client.campaigns.updateStatus(123, 'scheduled', {
+     *   send_at: '2026-02-01T10:00:00Z',
+     * });
+     *
+     * // Pause a running campaign
+     * await client.campaigns.updateStatus(123, 'paused');
+     *
+     * // Resume a paused campaign
+     * await client.campaigns.updateStatus(123, 'running');
+     * ```
+     */
+    updateStatus(id: number, status: Exclude<CampaignStatus, "finished">, options?: {
+        send_at?: string;
+    }): Promise<Campaign>;
+    /**
+     * Generates an HTML preview of the campaign.
+     *
+     * @param id - Campaign ID
+     * @param options - Preview options
+     * @param options.subscriber_id - Subscriber ID for personalization
+     * @param options.data - Custom template data
+     * @returns The preview response with rendered HTML
+     *
+     * @example
+     * ```typescript
+     * // Basic preview
+     * const preview = await client.campaigns.preview(123);
+     * console.log(preview.body);
+     *
+     * // Preview with subscriber personalization
+     * const personalized = await client.campaigns.preview(123, {
+     *   subscriber_id: 456,
+     * });
+     *
+     * // Preview with custom template data
+     * const custom = await client.campaigns.preview(123, {
+     *   data: {
+     *     Subscriber: { FirstName: 'John' },
+     *   },
+     * });
+     * ```
+     */
+    preview(id: number, options?: PreviewOptions): Promise<PreviewResponse>;
+    /**
+     * Generates a plain text preview of the campaign.
+     *
+     * @param id - Campaign ID
+     * @returns The preview response with plain text content
+     *
+     * @example
+     * ```typescript
+     * const textPreview = await client.campaigns.previewText(123);
+     * console.log(textPreview.body);
+     * ```
+     */
+    previewText(id: number): Promise<PreviewResponse>;
+    /**
+     * Retrieves real-time statistics for running campaigns.
+     *
+     * @param ids - Campaign IDs to get stats for
+     * @returns Array of campaign statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.campaigns.getRunningStats([1, 2, 3]);
+     * for (const stat of stats) {
+     *   const progress = (stat.sent / stat.to_send * 100).toFixed(1);
+     *   console.log(`${stat.name}: ${progress}% (${stat.rate} msg/s)`);
+     * }
+     * ```
+     */
+    getRunningStats(ids: number[]): Promise<CampaignStats[]>;
+    /**
+     * Retrieves analytics data for campaigns.
+     *
+     * @param type - Analytics type ('views', 'clicks', 'links', 'bounces')
+     * @param options - Query options
+     * @returns Analytics data (time-series for views/clicks/bounces, per-URL for links)
+     *
+     * @example
+     * ```typescript
+     * // Get view counts over time
+     * const views = await client.campaigns.getAnalytics('views', {
+     *   id: [123],
+     *   from: '2026-01-01T00:00:00Z',
+     *   to: '2026-01-31T23:59:59Z',
+     * });
+     *
+     * // Get per-link click breakdown
+     * const links = await client.campaigns.getAnalytics('links', {
+     *   id: [123],
+     * });
+     * for (const link of links) {
+     *   console.log(`${link.url}: ${link.count} clicks`);
+     * }
+     * ```
+     */
+    getAnalytics(type: AnalyticsType, options?: GetAnalyticsOptions): Promise<AnalyticsData[] | LinkAnalytics[]>;
+    /**
+     * Sends a test campaign to specified email addresses.
+     *
+     * @param id - Campaign ID
+     * @param options - Test send options
+     * @param options.subscribers - Email addresses to send test to
+     *
+     * @example
+     * ```typescript
+     * await client.campaigns.sendTest(123, {
+     *   subscribers: ['test1@example.com', 'test2@example.com'],
+     * });
+     * ```
+     */
+    sendTest(id: number, options: SendTestRequest): Promise<void>;
+    /**
+     * Archives or unarchives a campaign to/from the public archive.
+     *
+     * @param id - Campaign ID
+     * @param archive - Whether to archive (true) or unarchive (false)
+     * @param options - Additional archive options
+     * @returns The updated campaign
+     *
+     * @example
+     * ```typescript
+     * // Archive a campaign
+     * await client.campaigns.archive(123, true, {
+     *   archive_slug: 'january-newsletter',
+     *   archive_template_id: 2,
+     * });
+     *
+     * // Unarchive a campaign
+     * await client.campaigns.archive(123, false);
+     * ```
+     */
+    archive(id: number, archive?: boolean, options?: Omit<ArchiveRequest, "archive">): Promise<Campaign>;
+    /**
+     * Converts campaign content between formats.
+     *
+     * Note: Conversions are best-effort. Some formatting may be lost,
+     * especially when converting from rich formats to plain text.
+     *
+     * @param id - Campaign ID
+     * @param to - Target content format
+     * @returns The converted content
+     *
+     * @example
+     * ```typescript
+     * // Convert markdown to HTML
+     * const html = await client.campaigns.convertContent(123, 'html');
+     * console.log(html.body);
+     *
+     * // Convert to plain text
+     * const plain = await client.campaigns.convertContent(123, 'plain');
+     * ```
+     */
+    convertContent(id: number, to: CampaignContentType): Promise<PreviewResponse>;
+    /**
+     * Deletes multiple campaigns by ID.
+     *
+     * @param ids - Campaign IDs to delete
+     *
+     * @example
+     * ```typescript
+     * await client.campaigns.deleteMany([1, 2, 3]);
+     * ```
+     */
+    deleteMany(ids: number[]): Promise<void>;
+    /**
+     * Deletes campaigns matching a SQL-style query.
+     *
+     * @param query - SQL-style query expression
+     *
+     * @example
+     * ```typescript
+     * await client.campaigns.deleteByQuery("campaigns.status = 'draft'");
+     * ```
+     */
+    deleteByQuery(query: string): Promise<void>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Campaigns resource module.
+ *
+ * Provides complete campaign lifecycle management for the listmonk API.
+ *
+ * @module resources/campaigns
+ */
+export { CampaignsResource } from "./campaigns";
+export type { Campaign, CampaignStatus, CampaignType, CampaignContentType, AnalyticsType, Header, CampaignList, CampaignStats, AnalyticsData, LinkAnalytics, CreateCampaignRequest, UpdateCampaignRequest, ListCampaignsOptions, ListCampaignsResponse, UpdateStatusRequest, SendTestRequest, ArchiveRequest, GetAnalyticsOptions, PreviewResponse, PreviewOptions, BulkDeleteByQueryRequest, } from "./types";
+export { CampaignStatusSchema, CampaignTypeSchema, CampaignContentTypeSchema, AnalyticsTypeSchema, HeaderSchema, CampaignListSchema, CampaignSchema, CampaignStatsSchema, AnalyticsDataSchema, LinkAnalyticsSchema, CreateCampaignRequestSchema, UpdateCampaignRequestSchema, ListCampaignsOptionsSchema, ListCampaignsResponseSchema, UpdateStatusRequestSchema, SendTestRequestSchema, ArchiveRequestSchema, GetAnalyticsOptionsSchema, PreviewResponseSchema, PreviewOptionsSchema, BulkDeleteByQueryRequestSchema, } from "./schemas";