@solytude/listmonk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 solytude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,542 @@
+# @solytude/listmonk
+
+[![npm version](https://img.shields.io/npm/v/@solytude/listmonk)](https://www.npmjs.com/package/@solytude/listmonk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue)](https://www.typescriptlang.org/)
+
+Production-grade TypeScript SDK for the [listmonk](https://listmonk.app/) email marketing platform API.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Resources](#resources)
+- [Usage Examples](#usage-examples)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Pagination](#pagination)
+- [TypeScript](#typescript)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Complete API Coverage** — Full listmonk API coverage across 13 resource modules
+- **Type-Safe** — Full TypeScript support with strict typing and Zod runtime validation
+- **Zero Dependencies** — Only [Zod](https://zod.dev/) as a runtime dependency
+- **Modern Patterns** — Async iterators for pagination, AbortController for timeouts
+- **Stripe-Style API** — Intuitive resource-based interface (`client.subscribers.create()`)
+- **Resilient** — Automatic retries with exponential backoff and jitter
+- **Flexible** — Custom fetch support for edge runtimes and testing
+- **Secure** — HTTPS enforcement, credential redaction in debug mode
+
+## Requirements
+
+- **Node.js** 22+ or **Bun** 1.3+
+- **TypeScript** 5.7+ (optional, but recommended)
+
+## Installation
+
+```bash
+# npm
+npm install @solytude/listmonk
+
+# yarn
+yarn add @solytude/listmonk
+
+# pnpm
+pnpm add @solytude/listmonk
+
+# bun
+bun add @solytude/listmonk
+```
+
+## Quick Start
+
+```typescript
+import { Listmonk } from '@solytude/listmonk';
+
+const client = new Listmonk({
+  url: 'https://listmonk.example.com',
+  auth: {
+    username: process.env.LISTMONK_USERNAME!,
+    password: process.env.LISTMONK_PASSWORD!,
+  },
+});
+
+// Create a subscriber
+const subscriber = await client.subscribers.create({
+  email: 'user@example.com',
+  name: 'John Doe',
+  lists: [1, 2],
+});
+
+console.log(`Created subscriber: ${subscriber.id}`);
+```
+
+## Authentication
+
+The SDK uses Basic Authentication with username and password credentials. Create API credentials in your listmonk admin panel under **Settings → API**.
+
+### Using Environment Variables (Recommended)
+
+```bash
+export LISTMONK_URL=https://listmonk.example.com
+export LISTMONK_USERNAME=your_username
+export LISTMONK_PASSWORD=your_password
+```
+
+```typescript
+const client = new Listmonk({
+  url: process.env.LISTMONK_URL!,
+  auth: {
+    username: process.env.LISTMONK_USERNAME!,
+    password: process.env.LISTMONK_PASSWORD!,
+  },
+});
+```
+
+> **Security Warning**: Never commit credentials to version control. Always use environment variables or a secrets manager.
+
+## Resources
+
+The SDK provides access to all listmonk API resources:
+
+| Resource | Description | Methods |
+|----------|-------------|---------|
+| `subscribers` | Subscriber management, blocklisting, bounces | 17 |
+| `lists` | Mailing list CRUD operations | 5 |
+| `campaigns` | Campaign lifecycle, analytics, previews | 14 |
+| `templates` | Email template management | 8 |
+| `tx` | Transactional email sending | 1 |
+| `media` | Media file uploads and management | 4 |
+| `import` | Bulk subscriber imports (CSV/ZIP) | 4 |
+| `bounces` | Bounce record management | 4 |
+| `settings` | Server settings and SMTP configuration | 4 |
+| `dashboard` | Dashboard statistics and charts | 2 |
+| `admin` | Server administration and logs | 3 |
+| `maintenance` | Garbage collection and cleanup | 3 |
+| `public` | Public subscription endpoints | 3 |
+
+## Usage Examples
+
+### Subscribers
+
+```typescript
+// List subscribers with pagination
+const subscribers = await client.subscribers.list({
+  page: 1,
+  per_page: 100,
+  query: 'subscribers.status = \'enabled\'',
+});
+
+// Get a single subscriber
+const subscriber = await client.subscribers.get(123);
+
+// Update a subscriber
+await client.subscribers.update(123, {
+  name: 'Jane Doe',
+  attribs: { company: 'Acme Inc' },
+});
+
+// Delete a subscriber
+await client.subscribers.delete(123);
+
+// Bulk operations
+await client.subscribers.addToLists([1, 2, 3], { lists: [1, 2] });
+await client.subscribers.blocklist([4, 5, 6]);
+```
+
+### Campaigns
+
+```typescript
+// Create a campaign
+const campaign = await client.campaigns.create({
+  name: 'Weekly Newsletter',
+  subject: 'This Week in Tech',
+  lists: [1],
+  type: 'regular',
+  content_type: 'richtext',
+  body: '<h1>Hello {{.Subscriber.Name}}</h1>',
+});
+
+// Preview a campaign
+const preview = await client.campaigns.preview(campaign.id);
+
+// Send a test email
+await client.campaigns.test(campaign.id, {
+  subscribers: ['test@example.com'],
+});
+
+// Start the campaign
+await client.campaigns.updateStatus(campaign.id, 'running');
+
+// Get campaign analytics
+const analytics = await client.campaigns.analytics('clicks', {
+  campaign_id: campaign.id,
+});
+```
+
+### Transactional Email
+
+```typescript
+await client.tx.send({
+  subscriber_email: 'user@example.com',
+  template_id: 1,
+  data: {
+    order_id: '12345',
+    items: ['Widget A', 'Widget B'],
+  },
+});
+```
+
+### Lists
+
+```typescript
+// Create a list
+const list = await client.lists.create({
+  name: 'Newsletter Subscribers',
+  type: 'public',
+  optin: 'double',
+});
+
+// Get all lists
+const lists = await client.lists.list();
+```
+
+### Media
+
+```typescript
+// Upload a file
+const media = await client.media.upload({
+  file: new File([buffer], 'image.png', { type: 'image/png' }),
+});
+
+// List all media
+const files = await client.media.list();
+```
+
+## Configuration
+
+```typescript
+const client = new Listmonk({
+  // Required
+  url: 'https://listmonk.example.com',
+  auth: {
+    username: 'your_username',
+    password: 'your_password',
+  },
+
+  // Optional
+  timeout: 30000,           // Request timeout in ms (default: 30000)
+  maxRetries: 2,            // Max retry attempts (default: 2)
+  debug: false,             // Enable debug logging (default: false)
+  fetch: customFetch,       // Custom fetch implementation
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | — | listmonk server URL (required) |
+| `auth.username` | `string` | — | API username (required) |
+| `auth.password` | `string` | — | API password (required) |
+| `timeout` | `number` | `30000` | Request timeout in milliseconds |
+| `maxRetries` | `number` | `2` | Maximum retry attempts for failed requests |
+| `debug` | `boolean` | `false` | Enable debug logging (credentials redacted) |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
+
+## Error Handling
+
+The SDK provides a typed error hierarchy for granular error handling:
+
+```typescript
+import {
+  Listmonk,
+  ListmonkError,
+  ListmonkApiError,
+  ListmonkAuthenticationError,
+  ListmonkNotFoundError,
+  ListmonkRateLimitError,
+  ListmonkValidationError,
+  ListmonkNetworkError,
+} from '@solytude/listmonk';
+
+try {
+  await client.subscribers.get(999999);
+} catch (error) {
+  if (error instanceof ListmonkNotFoundError) {
+    console.error('Subscriber not found:', error.message);
+  } else if (error instanceof ListmonkAuthenticationError) {
+    console.error('Invalid credentials:', error.message);
+  } else if (error instanceof ListmonkRateLimitError) {
+    console.error('Rate limited. Retry after:', error.retryAfter);
+  } else if (error instanceof ListmonkValidationError) {
+    console.error('Validation failed:', error.issues);
+  } else if (error instanceof ListmonkApiError) {
+    console.error('API error:', error.status, error.message);
+  } else if (error instanceof ListmonkNetworkError) {
+    console.error('Network error:', error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Error Types
+
+| Error Class | HTTP Status | Description |
+|-------------|-------------|-------------|
+| `ListmonkBadRequestError` | 400 | Invalid request parameters |
+| `ListmonkAuthenticationError` | 401 | Invalid or missing credentials |
+| `ListmonkPermissionDeniedError` | 403 | Insufficient permissions |
+| `ListmonkNotFoundError` | 404 | Resource not found |
+| `ListmonkRateLimitError` | 429 | Too many requests |
+| `ListmonkInternalServerError` | 5xx | Server-side error |
+| `ListmonkValidationError` | — | Zod schema validation failed |
+| `ListmonkNetworkError` | — | Connection or timeout error |
+| `ListmonkConfigurationError` | — | Invalid client configuration |
+
+## Pagination
+
+### Async Iteration (Recommended)
+
+Iterate through all results automatically:
+
+```typescript
+for await (const subscriber of client.subscribers.listAll()) {
+  console.log(subscriber.email);
+}
+
+// With filtering
+for await (const subscriber of client.subscribers.listAll({
+  query: 'subscribers.status = \'enabled\'',
+})) {
+  console.log(subscriber.email);
+}
+```
+
+### Manual Pagination
+
+Control pagination manually when needed:
+
+```typescript
+let page = 1;
+let hasMore = true;
+
+while (hasMore) {
+  const response = await client.subscribers.list({
+    page,
+    per_page: 100,
+  });
+
+  for (const subscriber of response.data.results) {
+    console.log(subscriber.email);
+  }
+
+  hasMore = page * 100 < response.data.total;
+  page++;
+}
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and provides comprehensive type definitions. Types are inferred from Zod schemas, ensuring runtime validation matches compile-time types.
+
+### Importing Types
+
+```typescript
+import type {
+  Subscriber,
+  List,
+  Campaign,
+  Template,
+  CreateSubscriberParams,
+  UpdateCampaignParams,
+} from '@solytude/listmonk';
+```
+
+### Using Schemas
+
+Zod schemas are exported for custom validation or extension:
+
+```typescript
+import { SubscriberSchema, CreateSubscriberSchema } from '@solytude/listmonk';
+
+// Validate external data
+const subscriber = SubscriberSchema.parse(externalData);
+
+// Extend schemas
+const CustomSubscriberSchema = SubscriberSchema.extend({
+  customField: z.string(),
+});
+```
+
+## Testing
+
+The SDK provides test utilities for unit testing applications without real API calls:
+
+```bash
+# The testing module is included in the main package
+import { MockListmonkClient } from '@solytude/listmonk/testing';
+```
+
+### MockListmonkClient
+
+The `MockListmonkClient` provides a test-runner-agnostic mock implementation:
+
+```typescript
+import { MockListmonkClient, createMockSubscriber } from '@solytude/listmonk/testing';
+
+describe('MyApp', () => {
+  let mockClient: MockListmonkClient;
+
+  beforeEach(() => {
+    mockClient = new MockListmonkClient();
+  });
+
+  afterEach(() => {
+    mockClient.reset(); // Clears all mock configurations and call history
+  });
+
+  it('fetches subscribers', async () => {
+    // Configure mock response
+    mockClient.subscribers.list.mockResolvedValue({
+      data: {
+        results: [createMockSubscriber({ email: 'test@example.com' })],
+        total: 1,
+        per_page: 100,
+        page: 1,
+      },
+    });
+
+    // Use in your application code
+    const result = await mockClient.subscribers.list();
+
+    // Verify behavior
+    expect(result.data.results[0].email).toBe('test@example.com');
+    expect(mockClient.subscribers.list.callCount).toBe(1);
+  });
+
+  it('handles errors', async () => {
+    mockClient.subscribers.get.mockRejectedValue(new Error('Not found'));
+
+    await expect(mockClient.subscribers.get(999)).rejects.toThrow('Not found');
+  });
+});
+```
+
+### Mock Call Tracking
+
+All mock methods track calls for assertions:
+
+```typescript
+await mockClient.subscribers.create({ email: 'user@example.com', lists: [1] });
+
+expect(mockClient.subscribers.create.callCount).toBe(1);
+expect(mockClient.subscribers.create.lastCall).toEqual([
+  { email: 'user@example.com', lists: [1] }
+]);
+expect(mockClient.subscribers.create.calls).toHaveLength(1);
+```
+
+### Async Iterator Mocking
+
+Mock `listAll()` methods that return async iterators:
+
+```typescript
+mockClient.subscribers.listAll.mockAsyncIterator([
+  createMockSubscriber({ id: 1 }),
+  createMockSubscriber({ id: 2 }),
+  createMockSubscriber({ id: 3 }),
+]);
+
+const subscribers = [];
+for await (const sub of mockClient.subscribers.listAll()) {
+  subscribers.push(sub);
+}
+expect(subscribers).toHaveLength(3);
+```
+
+### Factory Functions
+
+Create realistic mock data with factory functions:
+
+```typescript
+import {
+  createMockSubscriber,
+  createMockSubscribers,
+  createMockList,
+  createMockCampaign,
+  createMockTemplate,
+  createMockMedia,
+  createMockBounce,
+  resetFactories,
+} from '@solytude/listmonk/testing';
+
+// Create single mock entities
+const subscriber = createMockSubscriber({ email: 'custom@example.com' });
+const list = createMockList({ name: 'Newsletter', type: 'private' });
+const campaign = createMockCampaign({ status: 'running' });
+
+// Create multiple mock entities
+const subscribers = createMockSubscribers(5); // 5 unique subscribers
+const lists = createMockLists(3, { type: 'private' }); // 3 private lists
+
+// Reset factory counters (call in beforeEach for predictable IDs)
+beforeEach(() => {
+  resetFactories();
+});
+```
+
+### Custom Fetch for Testing
+
+Inject a custom fetch function for fine-grained control:
+
+```typescript
+const mockFetch = vi.fn().mockResolvedValue(
+  new Response(JSON.stringify({ data: { id: 1 } }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+);
+
+const client = new Listmonk({
+  url: 'https://test.listmonk.app',
+  auth: { username: 'test', password: 'test' },
+  fetch: mockFetch,
+});
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+### Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Lint
+bun run check
+```
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+
+---
+
+**[listmonk](https://listmonk.app/)** is a free and open source, high performance, self-hosted newsletter and mailing list manager.

package/dist/chunk-saezhne8.js

@@ -0,0 +1,14 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+export { __export };
+
+//# debugId=934851CB66A4F95F64756E2164756E21

package/dist/chunk-saezhne8.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "934851CB66A4F95F64756E2164756E21",
+  "names": []
+}