@solytude/listmonk 1.0.0

package/dist/resources/subscribers/subscribers.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Subscribers resource for managing subscriber lifecycle.
+ *
+ * @module resources/subscribers
+ */
+import { APIResource } from "../../http/resource";
+import type { Subscriber, CreateSubscriberRequest, UpdateSubscriberRequest, ListSubscribersOptions, ListSubscribersResponse, ModifyListsRequest, ModifyListsForListRequest, ModifyListsByQueryRequest, BounceRecord, SubscriberExportResponse } from "./types";
+import type { PagedAsyncIterableIterator } from "../../types/pagination";
+/**
+ * Resource for managing subscribers in listmonk.
+ *
+ * Provides methods for CRUD operations, bulk operations,
+ * list membership management, and more.
+ *
+ * @example
+ * ```typescript
+ * // Access via client
+ * const subscriber = await client.subscribers.create({
+ *   email: 'john@example.com',
+ *   name: 'John Doe',
+ *   status: 'enabled',
+ * });
+ * ```
+ */
+export declare class SubscribersResource extends APIResource {
+    /**
+     * Creates a new subscriber.
+     *
+     * @param data - Subscriber data
+     * @returns The created subscriber
+     *
+     * @example
+     * ```typescript
+     * const subscriber = await client.subscribers.create({
+     *   email: 'john@example.com',
+     *   name: 'John Doe',
+     *   status: 'enabled',
+     *   lists: [1, 2],
+     *   attribs: { city: 'New York' },
+     * });
+     * ```
+     */
+    create(data: CreateSubscriberRequest): Promise<Subscriber>;
+    /**
+     * Retrieves a subscriber by ID.
+     *
+     * @param id - Subscriber ID
+     * @returns The subscriber
+     * @throws {ListmonkNotFoundError} If subscriber not found
+     *
+     * @example
+     * ```typescript
+     * const subscriber = await client.subscribers.retrieve(123);
+     * console.log(subscriber.email);
+     * ```
+     */
+    retrieve(id: number): Promise<Subscriber>;
+    /**
+     * Updates an existing subscriber.
+     *
+     * Note: The `lists` array replaces all existing list memberships.
+     * To modify lists without replacing, use `modifyLists()` instead.
+     *
+     * @param id - Subscriber ID
+     * @param data - Updated subscriber data
+     * @returns The updated subscriber
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.subscribers.update(123, {
+     *   email: 'john@example.com',
+     *   name: 'John Doe Updated',
+     *   status: 'enabled',
+     *   lists: [1, 2, 3],
+     * });
+     * ```
+     */
+    update(id: number, data: UpdateSubscriberRequest): Promise<Subscriber>;
+    /**
+     * Deletes a subscriber by ID.
+     *
+     * @param id - Subscriber ID
+     * @throws {ListmonkNotFoundError} If subscriber not found
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.remove(123);
+     * ```
+     */
+    remove(id: number): Promise<void>;
+    /**
+     * Lists subscribers with pagination and filtering.
+     *
+     * @param options - Query options
+     * @returns Paginated subscriber list
+     *
+     * @example
+     * ```typescript
+     * const page = await client.subscribers.list({
+     *   page: 1,
+     *   per_page: 50,
+     *   list_id: [1],
+     *   subscription_status: 'confirmed',
+     *   order_by: 'created_at',
+     *   order: 'DESC',
+     * });
+     * ```
+     */
+    list(options?: ListSubscribersOptions): Promise<ListSubscribersResponse>;
+    /**
+     * Returns an async iterator over all subscribers 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 subscribers
+     *
+     * @example
+     * ```typescript
+     * // Iterate over all subscribers
+     * for await (const subscriber of client.subscribers.listAll()) {
+     *   console.log(subscriber.email);
+     * }
+     *
+     * // Iterate over pages
+     * for await (const page of client.subscribers.listAll().byPage()) {
+     *   console.log(`Page ${page.page} has ${page.results.length} items`);
+     * }
+     * ```
+     */
+    listAll(options?: Omit<ListSubscribersOptions, "page">): PagedAsyncIterableIterator<Subscriber, ListSubscribersResponse>;
+    /**
+     * Modifies list memberships for multiple subscribers.
+     *
+     * @param request - Modification request with subscriber IDs, action, and target lists
+     *
+     * @example
+     * ```typescript
+     * // Add subscribers to lists
+     * await client.subscribers.modifyLists({
+     *   ids: [1, 2, 3],
+     *   action: 'add',
+     *   target_list_ids: [10, 20],
+     *   status: 'confirmed', // Required for 'add' action
+     * });
+     *
+     * // Remove subscribers from lists
+     * await client.subscribers.modifyLists({
+     *   ids: [1, 2],
+     *   action: 'remove',
+     *   target_list_ids: [10],
+     * });
+     * ```
+     */
+    modifyLists(request: ModifyListsRequest): Promise<void>;
+    /**
+     * Modifies list membership for a specific list.
+     *
+     * @param listId - Target list ID
+     * @param request - Modification request with subscriber IDs and action
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.modifyListsForList(10, {
+     *   ids: [1, 2, 3],
+     *   action: 'add',
+     *   status: 'confirmed',
+     * });
+     * ```
+     */
+    modifyListsForList(listId: number, request: ModifyListsForListRequest): Promise<void>;
+    /**
+     * Blocklists a single subscriber.
+     *
+     * @param id - Subscriber ID
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.blocklist(123);
+     * ```
+     */
+    blocklist(id: number): Promise<void>;
+    /**
+     * Blocklists multiple subscribers by ID.
+     *
+     * @param ids - Subscriber IDs
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.blocklistMany([1, 2, 3]);
+     * ```
+     */
+    blocklistMany(ids: number[]): Promise<void>;
+    /**
+     * Blocklists subscribers matching a SQL-style query.
+     *
+     * @param query - SQL-style query expression
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.blocklistByQuery(
+     *   "subscribers.attribs->>'source' = 'spam'"
+     * );
+     * ```
+     */
+    blocklistByQuery(query: string): Promise<void>;
+    /**
+     * Deletes multiple subscribers by ID.
+     *
+     * Note: This uses query parameters (?id=1&id=2), not a JSON body.
+     *
+     * @param ids - Subscriber IDs to delete
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.deleteMany([1, 2, 3]);
+     * ```
+     */
+    deleteMany(ids: number[]): Promise<void>;
+    /**
+     * Deletes subscribers matching a SQL-style query.
+     *
+     * @param query - SQL-style query expression
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.deleteByQuery(
+     *   "subscribers.status = 'disabled' AND subscribers.updated_at < '2023-01-01'"
+     * );
+     * ```
+     */
+    deleteByQuery(query: string): Promise<void>;
+    /**
+     * Retrieves bounce records for a subscriber.
+     *
+     * @param id - Subscriber ID
+     * @returns Array of bounce records
+     *
+     * @example
+     * ```typescript
+     * const bounces = await client.subscribers.getBounces(123);
+     * for (const bounce of bounces) {
+     *   console.log(bounce.type, bounce.source);
+     * }
+     * ```
+     */
+    getBounces(id: number): Promise<BounceRecord[]>;
+    /**
+     * Deletes all bounce records for a subscriber.
+     *
+     * @param id - Subscriber ID
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.deleteBounces(123);
+     * ```
+     */
+    deleteBounces(id: number): Promise<void>;
+    /**
+     * Exports complete subscriber data for GDPR/CCPA compliance.
+     *
+     * Includes profile, subscriptions, campaign views, and link clicks.
+     * Private list names are masked as "Private list".
+     *
+     * @param id - Subscriber ID
+     * @returns Complete subscriber export data
+     *
+     * @example
+     * ```typescript
+     * const data = await client.subscribers.export(123);
+     * console.log(data.profile);
+     * console.log(data.subscriptions);
+     * console.log(data.campaign_views);
+     * console.log(data.link_clicks);
+     * ```
+     */
+    export(id: number): Promise<SubscriberExportResponse>;
+    /**
+     * Sends an opt-in confirmation email to the subscriber.
+     *
+     * Used for double opt-in confirmation flows.
+     *
+     * @param id - Subscriber ID
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.sendOptin(123);
+     * ```
+     */
+    sendOptin(id: number): Promise<void>;
+    /**
+     * Modifies list memberships for subscribers matching a query.
+     *
+     * @param request - Modification request with query, action, and target lists
+     *
+     * @example
+     * ```typescript
+     * await client.subscribers.modifyListsByQuery({
+     *   query: "subscribers.attribs->>'segment' = 'vip'",
+     *   action: 'add',
+     *   target_list_ids: [10],
+     *   status: 'confirmed',
+     * });
+     * ```
+     */
+    modifyListsByQuery(request: ModifyListsByQueryRequest): Promise<void>;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * TypeScript types for subscribers module.
+ *
+ * All types are inferred from Zod schemas to ensure runtime
+ * validation matches compile-time types.
+ *
+ * @module resources/subscribers/types
+ */
+import type { z } from "zod";
+import type { SubscriberSchema, SubscriberStatusSchema, SubscriptionStatusSchema, ListSubscriptionSchema, BounceRecordSchema, BounceTypeSchema, BounceCampaignSchema, SubscriberAttribsSchema, CreateSubscriberRequestSchema, UpdateSubscriberRequestSchema, ListSubscribersOptionsSchema, ListSubscribersResponseSchema, ModifyListsRequestSchema, ModifyListsForListRequestSchema, ModifyListsByQueryRequestSchema, QueryOperationRequestSchema, BulkOperationResponseSchema, SubscriberExportResponseSchema, SubscriberProfileSchema, ExportSubscriptionSchema, CampaignViewSchema, LinkClickSchema, ListActionSchema } from "./schemas";
+/**
+ * Subscriber account-level status.
+ * - `enabled`: Active subscriber, can receive emails
+ * - `disabled`: Temporarily disabled, no emails sent
+ * - `blocklisted`: Permanently blocked from receiving emails
+ */
+export type SubscriberStatus = z.infer<typeof SubscriberStatusSchema>;
+/**
+ * Subscription status for a specific list.
+ * - `confirmed`: Subscription is active and confirmed
+ * - `unconfirmed`: Pending confirmation (double opt-in)
+ * - `unsubscribed`: User has unsubscribed from this list
+ */
+export type SubscriptionStatus = z.infer<typeof SubscriptionStatusSchema>;
+/**
+ * Actions for list membership modification.
+ * - `add`: Add subscribers to lists (requires status parameter)
+ * - `remove`: Remove subscribers from lists entirely
+ * - `unsubscribe`: Mark as unsubscribed (soft removal, keeps record)
+ */
+export type ListAction = z.infer<typeof ListActionSchema>;
+/**
+ * Bounce type classification.
+ * - `hard`: Permanent delivery failure
+ * - `soft`: Temporary delivery failure
+ */
+export type BounceType = z.infer<typeof BounceTypeSchema>;
+/**
+ * Custom subscriber attributes (flexible JSON object).
+ */
+export type SubscriberAttribs = z.infer<typeof SubscriberAttribsSchema>;
+/**
+ * Campaign info attached to a bounce record.
+ */
+export type BounceCampaign = z.infer<typeof BounceCampaignSchema>;
+/**
+ * List subscription details within a subscriber.
+ */
+export type ListSubscription = z.infer<typeof ListSubscriptionSchema>;
+/**
+ * Complete subscriber entity.
+ */
+export type Subscriber = z.infer<typeof SubscriberSchema>;
+/**
+ * Bounce record for email delivery failures.
+ */
+export type BounceRecord = z.infer<typeof BounceRecordSchema>;
+/**
+ * Request to create a new subscriber (input type).
+ */
+export type CreateSubscriberRequest = z.input<typeof CreateSubscriberRequestSchema>;
+/**
+ * Request to update an existing subscriber (input type).
+ */
+export type UpdateSubscriberRequest = z.input<typeof UpdateSubscriberRequestSchema>;
+/**
+ * Options for listing subscribers (input type).
+ */
+export type ListSubscribersOptions = z.input<typeof ListSubscribersOptionsSchema>;
+/**
+ * Request to modify list memberships for subscribers by ID (input type).
+ */
+export type ModifyListsRequest = z.input<typeof ModifyListsRequestSchema>;
+/**
+ * Request to modify list memberships for a specific list (input type).
+ */
+export type ModifyListsForListRequest = z.input<typeof ModifyListsForListRequestSchema>;
+/**
+ * Request to modify list memberships by SQL-style query (input type).
+ */
+export type ModifyListsByQueryRequest = z.input<typeof ModifyListsByQueryRequestSchema>;
+/**
+ * Request for query-based operations (delete, blocklist).
+ */
+export type QueryOperationRequest = z.input<typeof QueryOperationRequestSchema>;
+/**
+ * Paginated list of subscribers response.
+ */
+export type ListSubscribersResponse = z.infer<typeof ListSubscribersResponseSchema>;
+/**
+ * Response for bulk operations.
+ */
+export type BulkOperationResponse = z.infer<typeof BulkOperationResponseSchema>;
+/**
+ * Subscriber profile in export.
+ */
+export type SubscriberProfile = z.infer<typeof SubscriberProfileSchema>;
+/**
+ * Subscription in export (private list names masked).
+ */
+export type ExportSubscription = z.infer<typeof ExportSubscriptionSchema>;
+/**
+ * Campaign view in export.
+ */
+export type CampaignView = z.infer<typeof CampaignViewSchema>;
+/**
+ * Link click in export.
+ */
+export type LinkClick = z.infer<typeof LinkClickSchema>;
+/**
+ * Complete subscriber export response.
+ */
+export type SubscriberExportResponse = z.infer<typeof SubscriberExportResponseSchema>;

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

@@ -0,0 +1,10 @@
+/**
+ * Templates resource module.
+ *
+ * Provides complete template management for the listmonk API.
+ *
+ * @module resources/templates
+ */
+export { TemplatesResource } from "./templates";
+export type { Template, TemplateType, TemplatePreview, CreateTemplateRequest, UpdateTemplateRequest, ListTemplatesOptions, LivePreviewRequest, ListTemplatesResponse, } from "./types";
+export { TemplateTypeSchema, TemplateSchema, TemplatePreviewSchema, CreateTemplateRequestSchema, UpdateTemplateRequestSchema, ListTemplatesOptionsSchema, LivePreviewRequestSchema, ListTemplatesResponseSchema, } from "./schemas";

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

@@ -0,0 +1,110 @@
+/**
+ * Zod schemas for template-related requests and responses.
+ *
+ * @module resources/templates/schemas
+ */
+import { z } from "zod";
+/**
+ * Template type.
+ * - `campaign`: Standard campaign email templates
+ * - `campaign_visual`: Visual drag-and-drop editor templates
+ * - `tx`: Transactional email templates
+ */
+export declare const TemplateTypeSchema: z.ZodEnum<{
+    campaign: "campaign";
+    campaign_visual: "campaign_visual";
+    tx: "tx";
+}>;
+/**
+ * Complete template entity returned from API.
+ */
+export declare const TemplateSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    uuid: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    body: z.ZodString;
+    body_source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodEnum<{
+        campaign: "campaign";
+        campaign_visual: "campaign_visual";
+        tx: "tx";
+    }>;
+    subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_default: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Template preview response.
+ */
+export declare const TemplatePreviewSchema: z.ZodObject<{
+    body: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Request to create a new template.
+ */
+export declare const CreateTemplateRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    body: z.ZodString;
+    type: z.ZodEnum<{
+        campaign: "campaign";
+        campaign_visual: "campaign_visual";
+        tx: "tx";
+    }>;
+    subject: z.ZodOptional<z.ZodString>;
+    body_source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Request to update an existing template.
+ * All fields are optional for partial updates.
+ */
+export declare const UpdateTemplateRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        campaign: "campaign";
+        campaign_visual: "campaign_visual";
+        tx: "tx";
+    }>>;
+    subject: z.ZodOptional<z.ZodString>;
+    body_source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Options for listing templates.
+ */
+export declare const ListTemplatesOptionsSchema: z.ZodObject<{
+    no_body: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Request for live template preview (POST /api/templates/preview).
+ */
+export declare const LivePreviewRequestSchema: z.ZodObject<{
+    template_type: z.ZodEnum<{
+        campaign: "campaign";
+        campaign_visual: "campaign_visual";
+        tx: "tx";
+    }>;
+    body: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Response for listing all templates.
+ * Note: Unlike paginated endpoints, templates returns a simple array wrapped in { data: [] }.
+ */
+export declare const ListTemplatesResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        uuid: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        body: z.ZodString;
+        body_source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        type: z.ZodEnum<{
+            campaign: "campaign";
+            campaign_visual: "campaign_visual";
+            tx: "tx";
+        }>;
+        subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        is_default: z.ZodBoolean;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;