@solytude/listmonk 1.0.0

package/dist/testing/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Testing utility types for mock functions and mock client.
+ *
+ * @module testing/types
+ */
+/**
+ * Result of a mock function call.
+ */
+export interface MockResult<T> {
+    /** Whether the call returned or threw */
+    type: "return" | "throw";
+    /** The returned value or thrown error */
+    value: T | Error;
+}
+/**
+ * Internal state tracking for mock function calls.
+ */
+export interface MockState<TArgs extends unknown[], TReturn> {
+    /** Array of argument arrays from each invocation */
+    calls: TArgs[];
+    /** Array of results (return values or thrown errors) */
+    results: MockResult<TReturn>[];
+    /** Arguments from the most recent call, or undefined if never called */
+    lastCall: TArgs | undefined;
+    /** Total number of times the mock was called */
+    callCount: number;
+}
+/**
+ * Generic mock function interface.
+ *
+ * Replaces a real function with a configurable mock that tracks calls
+ * and can return predetermined values or throw errors.
+ *
+ * @typeParam TArgs - The function argument types
+ * @typeParam TReturn - The function return type
+ *
+ * @example
+ * ```typescript
+ * const mockCreate = createMockFunction<[CreateSubscriberInput], Promise<Subscriber>>(
+ *   'subscribers',
+ *   'create'
+ * );
+ *
+ * // Configure return value
+ * mockCreate.mockResolvedValue({ id: 1, email: 'test@example.com', ... });
+ *
+ * // Use the mock
+ * const result = await mockCreate({ email: 'test@example.com' });
+ *
+ * // Verify calls
+ * expect(mockCreate.mock.callCount).toBe(1);
+ * expect(mockCreate.mock.calls[0]).toEqual([{ email: 'test@example.com' }]);
+ * ```
+ */
+export interface MockFunction<TArgs extends unknown[], TReturn> {
+    /**
+     * Invoke the mock function.
+     * Returns the configured value or throws the configured error.
+     *
+     * @throws {MockNotConfiguredError} If no mock value/implementation configured
+     */
+    (...args: TArgs): TReturn;
+    /**
+     * Internal mock state tracking.
+     */
+    mock: MockState<TArgs, Awaited<TReturn>>;
+    /**
+     * Configure the mock to resolve with the given value.
+     * For async functions, wraps the value in Promise.resolve().
+     *
+     * @param value - The value to resolve with
+     * @returns The mock function for chaining
+     */
+    mockResolvedValue(value: Awaited<TReturn>): this;
+    /**
+     * Configure the mock to reject with the given error.
+     * For async functions, wraps the error in Promise.reject().
+     *
+     * @param error - The error to reject with
+     * @returns The mock function for chaining
+     */
+    mockRejectedValue(error: Error): this;
+    /**
+     * Configure the mock with a custom implementation.
+     * The implementation receives the same arguments as the real function.
+     *
+     * @param fn - The implementation function
+     * @returns The mock function for chaining
+     */
+    mockImplementation(fn: (...args: TArgs) => TReturn): this;
+    /**
+     * Configure the mock to return the given value synchronously.
+     * For sync functions only.
+     *
+     * @param value - The value to return
+     * @returns The mock function for chaining
+     */
+    mockReturnValue(value: TReturn): this;
+    /**
+     * Configure the mock to return an async iterator yielding the given values.
+     * Used for methods like listAll() that return AsyncIterableIterator.
+     *
+     * @param values - The values to yield
+     * @returns The mock function for chaining
+     */
+    mockAsyncIterator<T>(values: T[]): this;
+    /**
+     * Clear call history and results, but keep the configured implementation.
+     *
+     * @returns The mock function for chaining
+     */
+    mockClear(): this;
+    /**
+     * Reset the mock to unconfigured state.
+     * Clears call history, results, and implementation.
+     *
+     * @returns The mock function for chaining
+     */
+    mockReset(): this;
+}
+/**
+ * Type helper for extracting argument types from a function.
+ */
+export type MockArgs<T> = T extends (...args: infer A) => unknown ? A : never;
+/**
+ * Type helper for extracting return type from a function.
+ */
+export type MockReturn<T> = T extends (...args: unknown[]) => infer R ? R : never;
+/**
+ * Type helper for converting a method to its mocked version.
+ */
+export type Mocked<T> = T extends (...args: infer A) => infer R ? MockFunction<A, R> : never;
+/**
+ * Type helper for converting all methods of an object to mocks.
+ */
+export type MockedObject<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? MockFunction<A, R> : T[K];
+};

package/dist/types/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Client configuration types and Zod schema.
+ *
+ * Defines the shape of options passed to the Listmonk client constructor.
+ *
+ * @module types/config
+ */
+import { z } from "zod";
+import type { RequestHook, ResponseHook } from "../http/hooks";
+/**
+ * Type for custom fetch implementations.
+ * Compatible with both browser fetch and custom implementations.
+ */
+export type FetchLike = (input: string | Request | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Authentication credentials schema.
+ */
+export declare const AuthCredentialsSchema: z.ZodObject<{
+    username: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Authentication credentials type.
+ */
+export type AuthCredentials = z.infer<typeof AuthCredentialsSchema>;
+/**
+ * Client options Zod schema with runtime validation.
+ *
+ * Validates:
+ * - URL must be valid HTTPS
+ * - Auth credentials must be non-empty
+ * - Timeout must be non-negative integer
+ * - MaxRetries must be non-negative integer
+ */
+export declare const ClientOptionsSchema: z.ZodObject<{
+    url: z.ZodString;
+    auth: z.ZodObject<{
+        username: z.ZodString;
+        password: z.ZodString;
+    }, z.core.$strip>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxRetries: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    debug: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    fetch: z.ZodOptional<z.ZodCustom<FetchLike, FetchLike>>;
+    onRequest: z.ZodOptional<z.ZodCustom<RequestHook, RequestHook>>;
+    onResponse: z.ZodOptional<z.ZodCustom<ResponseHook, ResponseHook>>;
+}, z.core.$strict>;
+/**
+ * Client options type inferred from schema.
+ *
+ * Use this type when accepting configuration from users.
+ */
+export type ClientOptions = z.infer<typeof ClientOptionsSchema>;
+/**
+ * Input type for ClientOptions (before defaults are applied).
+ *
+ * Use this type for the constructor parameter.
+ */
+export type ClientOptionsInput = z.input<typeof ClientOptionsSchema>;

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type exports for the listmonk SDK.
+ *
+ * @module types
+ */
+export { ClientOptionsSchema, AuthCredentialsSchema, type ClientOptions, type ClientOptionsInput, type AuthCredentials, type FetchLike, } from "./config";
+export type { PagedAsyncIterableIterator } from "./pagination";

package/dist/types/pagination.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pagination types for async iteration over API results.
+ *
+ * @module types/pagination
+ */
+/**
+ * Async iterator that yields items with page-level iteration support.
+ *
+ * This interface extends `AsyncIterableIterator` to provide both
+ * item-by-item iteration and page-by-page iteration for paginated
+ * API responses.
+ *
+ * @typeParam T - The type of items yielded (e.g., Subscriber, List)
+ * @typeParam TPage - The type of page objects (e.g., ListSubscribersResponse)
+ *
+ * @example
+ * ```typescript
+ * // Iterate over individual items
+ * for await (const item of client.resource.listAll()) {
+ *   console.log(item);
+ * }
+ *
+ * // Iterate over pages
+ * for await (const page of client.resource.listAll().byPage()) {
+ *   console.log(`Page ${page.page} has ${page.results.length} items`);
+ * }
+ * ```
+ */
+export interface PagedAsyncIterableIterator<T, TPage = T[]> extends AsyncIterableIterator<T> {
+    /**
+     * Returns an async iterator that yields pages instead of individual items.
+     *
+     * Use this when you need access to page-level metadata (total count,
+     * current page number, etc.) or want to process items in batches.
+     */
+    byPage(): AsyncIterableIterator<TPage>;
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+	"name": "@solytude/listmonk",
+	"version": "1.0.0",
+	"description": "Production-grade TypeScript SDK for the listmonk email marketing platform API",
+	"author": "solytude",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./testing": {
+			"types": "./dist/testing/index.d.ts",
+			"import": "./dist/testing/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"typesVersions": {
+		"*": {
+			"testing": [
+				"./dist/testing/index.d.ts"
+			]
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"packageManager": "bun@1.3.5",
+	"engines": {
+		"bun": ">=1.3.0",
+		"node": ">=22.0.0"
+	},
+	"keywords": [
+		"listmonk",
+		"email",
+		"newsletter",
+		"mailing list",
+		"typescript",
+		"sdk",
+		"api",
+		"email marketing"
+	],
+	"homepage": "https://solytude.com/projects/listmonk-sdk",
+	"bugs": {
+		"url": "https://codeberg.org/solytude/listmonk-sdk/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://codeberg.org/solytude/listmonk-sdk.git"
+	},
+	"scripts": {
+		"build": "bun run build:js && bun run build:types",
+		"build:js": "bun run scripts/build.ts",
+		"build:types": "tsc -p tsconfig.build.json",
+		"test": "bun test tests/",
+		"test:unit": "bun test tests/unit/",
+		"test:integration": "bun test tests/integration/",
+		"test:e2e": "bun test tests/e2e/",
+		"check": "biome check",
+		"lint": "biome lint --write",
+		"format": "biome format --write",
+		"typecheck": "tsc -p tsconfig.check.json",
+		"docs": "typedoc",
+		"prepublishOnly": "bun run build && bun test tests/unit/ tests/integration/"
+	},
+	"dependencies": {
+		"zod": "^4.3.5"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org"
+	},
+	"overrides": {
+		"got": "11.8.5"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.11",
+		"@bun-security-scanner/osv": "^1.0.0",
+		"@commitlint/cli": "^20.3.0",
+		"@commitlint/config-conventional": "^20.3.0",
+		"@saithodev/semantic-release-gitea": "^2.0.0",
+		"@semantic-release/changelog": "^6.0.0",
+		"@semantic-release/git": "^10.0.0",
+		"@tsconfig/bun": "^1.0.10",
+		"@types/bun": "^1.3.5",
+		"semantic-release": "^25.0.0",
+		"typedoc": "^0.28.15",
+		"typedoc-plugin-markdown": "^4.0.0",
+		"typescript": "^5.9.3"
+	}
+}