mailchannels-sdk 0.7.10 → 0.8.0-0

package/README.md

@@ -6,10 +6,12 @@
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![codecov][codecov-coverage-src]][codecov-coverage-href]
 
-Node.js SDK to integrate [MailChannels API](https://docs.mailchannels.net/) into your JavaScript or TypeScript server-side applications.
+> Built and tested against Email API `0.21.1`
+
+Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.net/email-api) into your JavaScript or TypeScript server-side applications.
 
 <!-- #region overview -->
-This library provides a simple way to interact with the [MailChannels API](https://docs.mailchannels.net/). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
+This library provides a simple way to interact with the [MailChannels Email API](https://docs.mailchannels.net/email-api). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
 <!-- #endregion overview -->
 
 - [✨ Release Notes](CHANGELOG.md)
@@ -18,18 +20,18 @@ This library provides a simple way to interact with the [MailChannels API](https
 ## Contents
 
 - 🚀 [Features](#features)
-- 📏 [Requirements](#requirements)
+- 📏 [Prerequisites](#prerequisites)
 - 📦 [Installation](#installation)
 - 📚 [Usage](#usage)
 - 📐 [Naming Conventions](#naming-conventions)
+- 🧪 [Local simulator](#local-simulator)
 - ⚖️ [License](#license)
 - 💻 [Development](#development)
-- 🧪 [Local simulator](#local-simulator)
 
 ## <a name="features">🚀 Features</a>
 
 <!-- #region features -->
-This SDK fully supports all features and operations available in the [MailChannels API](https://docs.mailchannels.net/). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
+This SDK fully supports all features and operations available in the [MailChannels Email API](https://docs.mailchannels.net/email-api). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
 
 Some of the things you can do with the SDK:
 
@@ -41,14 +43,13 @@ Some of the things you can do with the SDK:
 - Retrieve metrics
 - Inspect webhook delivery batches
 - Handle suppressions
-- Configure inbound domains
-- Manage account and recipient lists
+- Run a local simulator for development testing
 
 > [!TIP]
 > For a detailed reference mapping each SDK method to its corresponding MailChannels API endpoint reference, see the [SDK-API Mapping](https://mailchannels.yizack.com/sdk-api-mapping)
 <!-- #endregion features -->
 
-## <a name="requirements">📏 Requirements</a>
+## <a name="prerequisites">📏 Prerequisites</a>
 
 - [Create a MailChannels account](https://www.mailchannels.com/pricing/#for_devs)
 - [Create an API key](https://console.mailchannels.net/settings/accountSettings#APIKeys)
@@ -101,59 +102,43 @@ Most properties in the MailChannels API use `snake_case`. To follow JavaScript c
 - While most fields match the API docs (just with `camelCase`), a few may be simplified or reorganized to feel more natural for JavaScript developers.
 <!-- #endregion naming-conventions -->
 
-## <a name="license">⚖️ License</a>
-
-[MIT License](LICENSE)
-
-## <a name="development">💻 Development</a>
-
-<details>
-  <summary>Local development</summary>
-
-```sh
-# Install dependencies
-pnpm install
-
-# Build the package
-pnpm build
-
-# Run Oxlint
-pnpm lint
+## <a name="local-simulator">🧪 Local simulator</a>
 
-# Run Vitest
-pnpm test
-pnpm test:watch
+<!-- #region simulator -->
+This package includes a local MailChannels simulator you can run via the CLI. It holds state in memory and emulates the SDK-supported endpoints, letting you develop and test your application locally without hitting the real MailChannels service.
 
-# Run typecheck
-pnpm test:types
+| API         | Source                                                                                                         |
+| ----------- | -------------------------------------------------------------------------------------------------------------- |
+| Email API   | [`src/simulator/email-api.mjs`](https://github.com/Yizack/mailchannels/blob/main/src/simulator/email-api.mjs)  |
 
-# Refresh API parity fixtures
-pnpm parity:fixtures
+> [!IMPORTANT]
+> The simulator approximates the MailChannels service for local development and testing. It is not a production implementation and may differ from the live service.
 
-# Run the local Email API simulator
-pnpm simulate:email-api
+### Start the simulator
 
-# Release new version
-pnpm release
+```sh
+# default: http://127.0.0.1:8787
+npx mailchannels-sdk simulate
 ```
 
-</details>
-
-## <a name="local-simulator">🧪 Local simulator</a>
+### Options
 
-This repo includes a small local MailChannels Email API simulator at [scripts/email-api-simulator.mjs](./scripts/email-api-simulator.mjs). It keeps state in memory and emulates the SDK-supported Email API endpoints so you can test your application without calling the real MailChannels service.
+| Option            | Description             | Default     |
+| ----------------- | ----------------------- | ----------- |
+| `--port <number>` | Port to listen on       | `8787`      |
+| `--host <host>`   | Host address            | `127.0.0.1` |
+| `--silent`        | Suppress simulator logs | `false`     |
 
-### Start the simulator
+You can override the bind address with the `--host` and `--port` options:
 
 ```sh
-# default: http://127.0.0.1:8787
-pnpm simulate:email-api
+npx mailchannels-sdk simulate --host 127.0.0.1 --port 8787
 ```
 
-You can override the bind address with environment variables:
+Disable logs with the `--silent` option:
 
 ```sh
-MAILCHANNELS_SIMULATOR_HOST=127.0.0.1 MAILCHANNELS_SIMULATOR_PORT=8787 pnpm simulate:email-api
+npx mailchannels-sdk simulate --silent
 ```
 
 ### Point the SDK at the simulator
@@ -192,6 +177,48 @@ const { data, error } = await mailchannels.emails.send({
 - Webhook responses are simulated locally, but the simulator does not yet emit real webhook callbacks to your application
 
 The next planned expansion is outbound webhook delivery so client applications can test webhook ingestion flows against the simulator as well.
+<!-- #endregion simulator -->
+
+## <a name="license">⚖️ License</a>
+
+[MIT License](LICENSE)
+
+## <a name="development">💻 Development</a>
+
+<details>
+  <summary>Local development</summary>
+
+```sh
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Run Oxlint
+pnpm lint
+
+# Run Vitest
+pnpm test
+pnpm test:watch
+
+# Run typecheck
+pnpm test:types
+
+# Refresh API parity fixtures
+pnpm parity:fixtures
+
+# Run the local simulator
+pnpm simulate
+
+# Run a playground script
+npx jiti playground/emails/send.ts
+
+# Release new version
+pnpm release
+```
+
+</details>
 
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/mailchannels-sdk.svg?style=flat&colorA=070a30&colorB=35a047