sendpro-flowmailer-mcp 0.1.1

package/.env.example

@@ -0,0 +1,19 @@
+SENDPRO_ACCOUNT_ID=your-account-id
+SENDPRO_CLIENT_ID=your-client-id
+SENDPRO_CLIENT_SECRET=your-client-secret
+
+# Safe default is true. Set to false only when you want write tools enabled.
+SENDPRO_READ_ONLY=true
+
+# READ_ONLY is also supported for MCP clients that pass generic env names.
+# READ_ONLY=true
+
+SENDPRO_API_BASE_URL=https://api.flowmailer.net
+SENDPRO_AUTH_BASE_URL=https://login.flowmailer.net
+SENDPRO_API_MEDIA_TYPE=application/vnd.flowmailer.v1.12+json
+
+# Legacy aliases are also supported:
+# FLOWMAILER_ACCOUNT_ID=your-account-id
+# FLOWMAILER_CLIENT_ID=your-client-id
+# FLOWMAILER_CLIENT_SECRET=your-client-secret
+# FLOWMAILER_READ_ONLY=true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sociuu
+
+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,295 @@
+# Spotler SendPro / FlowMailer MCP Server
+
+[![GitHub Release](https://img.shields.io/github/v/release/Mestika/sendpro-flowmailer-mcp?sort=semver&display_name=tag)](https://github.com/Mestika/sendpro-flowmailer-mcp/releases)
+[![npm version](https://img.shields.io/npm/v/sendpro-flowmailer-mcp.svg)](https://www.npmjs.com/package/sendpro-flowmailer-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/sendpro-flowmailer-mcp.svg)](https://www.npmjs.com/package/sendpro-flowmailer-mcp)
+[![CI](https://github.com/Mestika/sendpro-flowmailer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mestika/sendpro-flowmailer-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Mestika/sendpro-flowmailer-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/Mestika/sendpro-flowmailer-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178c6?logo=typescript&logoColor=white)](tsconfig.json)
+[![MCP](https://img.shields.io/badge/MCP-stdio-blue)](https://modelcontextprotocol.io/)
+[![Read-only default](https://img.shields.io/badge/read--only-default-success)](#read-only-mode)
+
+Unofficial Model Context Protocol server for the Spotler SendPro API, formerly known as FlowMailer.
+
+This project is not affiliated with, endorsed by, or maintained by Spotler. It is a community MCP server for teams that need controlled AI-agent access to SendPro account data and, when explicitly enabled, SendPro message operations.
+
+<!-- mcp-name: io.github.mestika/sendpro-flowmailer-mcp -->
+
+## What It Does
+
+- Connects to SendPro over OAuth2 client credentials.
+- Exposes SendPro operations as MCP tools over stdio.
+- Defaults to read-only mode.
+- Blocks mutating SendPro requests when read-only mode is enabled.
+- Supports current SendPro naming plus legacy FlowMailer environment variables.
+- Includes MCP Registry metadata in [server.json](server.json).
+
+## Install
+
+From npm:
+
+```bash
+npx -y sendpro-flowmailer-mcp
+```
+
+Directly from GitHub:
+
+```bash
+npx -y github:Mestika/sendpro-flowmailer-mcp
+```
+
+Local development:
+
+```bash
+git clone https://github.com/Mestika/sendpro-flowmailer-mcp.git
+cd sendpro-flowmailer-mcp
+npm install
+npm run build
+node dist/index.js
+```
+
+## Configuration
+
+Set credentials through your MCP client config, shell environment, or a local `.env` file.
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `SENDPRO_ACCOUNT_ID` | Yes | | SendPro account id. |
+| `SENDPRO_CLIENT_ID` | Yes | | OAuth client id. |
+| `SENDPRO_CLIENT_SECRET` | Yes | | OAuth client secret. |
+| `SENDPRO_READ_ONLY` | No | `true` | Safe-mode flag. When true, only SendPro read requests are allowed. |
+| `READ_ONLY` | No | | Generic override for `SENDPRO_READ_ONLY`; useful for shared MCP config conventions. |
+| `SENDPRO_API_BASE_URL` | No | `https://api.flowmailer.net` | SendPro API base URL. |
+| `SENDPRO_AUTH_BASE_URL` | No | `https://login.flowmailer.net` | OAuth base URL. |
+| `SENDPRO_API_MEDIA_TYPE` | No | `application/vnd.flowmailer.v1.12+json` | SendPro vendor media type. |
+
+Legacy aliases are supported:
+
+| Current | Spotler alias | Legacy FlowMailer alias |
+| --- | --- | --- |
+| `SENDPRO_ACCOUNT_ID` | `SPOTLER_SENDPRO_ACCOUNT_ID` | `FLOWMAILER_ACCOUNT_ID` |
+| `SENDPRO_CLIENT_ID` | `SPOTLER_SENDPRO_CLIENT_ID` | `FLOWMAILER_CLIENT_ID` |
+| `SENDPRO_CLIENT_SECRET` | `SPOTLER_SENDPRO_CLIENT_SECRET` | `FLOWMAILER_CLIENT_SECRET` |
+| `SENDPRO_READ_ONLY` | `SPOTLER_SENDPRO_READ_ONLY` | `FLOWMAILER_READ_ONLY` |
+
+Precedence is: `READ_ONLY`, then `SENDPRO_*`, then `SPOTLER_SENDPRO_*`, then `FLOWMAILER_*`.
+
+## Creating SendPro API Credentials
+
+SendPro uses OAuth2 client credentials. You need three values:
+
+- account id
+- client id
+- client secret
+
+The public SendPro API docs state that the API uses OAuth2 client credentials, that the access token endpoint is `https://login.flowmailer.net/oauth/token`, and that the `client_id`, `client_secret`, `grant_type=client_credentials`, and optional `scope=api` form values are used to request a token. The same docs also expose source-system credential endpoints under `/{account_id}/sources/{source_id}/users`, including endpoints to list, create, get, update, and delete source credentials.
+
+In the SendPro dashboard, the exact labels can vary by account, but the usual path is:
+
+1. Sign in to Spotler SendPro.
+2. Go to Setup.
+3. Open Sources or Source systems.
+4. Select the source system that should be used for API access, or create a dedicated source for MCP/automation usage.
+5. Open the source credentials/users section.
+6. Create new credentials with a clear description such as `MCP read-only`.
+7. Copy the generated client id and client secret, and store them in your MCP client environment.
+8. Use the SendPro account id from your account URL, dashboard context, or API settings as `SENDPRO_ACCOUNT_ID`.
+
+For AI-agent usage, prefer credentials that are limited to the minimum access needed. Keep this MCP server in read-only mode unless you explicitly need submit, simulate, or resend operations.
+
+Official references:
+
+- [SendPro API authentication](https://flowmailer.com/apidoc/sendpro-api.html#_authentication)
+- [POST `/oauth/token`](https://flowmailer.com/apidoc/sendpro-api.html#_post_oauth_token)
+- [Source credential endpoints](https://flowmailer.com/apidoc/sendpro-api.html#_post_account_id_sources_source_id_users)
+- [Spotler SendPro Help Center](https://sendpro.spotler.help/hc/en-gb)
+
+## Codex
+
+Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.sendpro_flowmailer]
+command = "npx"
+args = ["-y", "sendpro-flowmailer-mcp"]
+startup_timeout_sec = 20.0
+
+[mcp_servers.sendpro_flowmailer.env]
+SENDPRO_ACCOUNT_ID = "your-account-id"
+SENDPRO_CLIENT_ID = "your-client-id"
+SENDPRO_CLIENT_SECRET = "your-client-secret"
+SENDPRO_READ_ONLY = "true"
+```
+
+To run directly from GitHub:
+
+```toml
+[mcp_servers.sendpro_flowmailer]
+command = "npx"
+args = ["-y", "github:Mestika/sendpro-flowmailer-mcp"]
+startup_timeout_sec = 20.0
+```
+
+## Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sendpro-flowmailer": {
+      "command": "npx",
+      "args": ["-y", "sendpro-flowmailer-mcp"],
+      "env": {
+        "SENDPRO_ACCOUNT_ID": "your-account-id",
+        "SENDPRO_CLIENT_ID": "your-client-id",
+        "SENDPRO_CLIENT_SECRET": "your-client-secret",
+        "SENDPRO_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+## Read-Only Mode
+
+`SENDPRO_READ_ONLY` defaults to `true`.
+
+When read-only mode is enabled:
+
+- MCP schemas only allow `GET` for the generic request tool.
+- Mutating helper tools are not registered.
+- The low-level client rejects `POST`, `PUT`, `PATCH`, and `DELETE` SendPro API requests before requesting an OAuth token.
+
+OAuth itself still uses `POST https://login.flowmailer.net/oauth/token`, because SendPro requires OAuth2 client credentials before any resource can be read. The read-only guard applies to SendPro API resource calls against the configured API base URL.
+
+## Tools
+
+Read tools:
+
+| Tool | Description |
+| --- | --- |
+| `flowmailer_request` | Generic relative SendPro API request. In read-only mode, only `GET` is accepted. |
+| `flowmailer_endpoint_catalog` | Lists SendPro endpoints known by this server. |
+| `flowmailer_list_messages` | Lists messages using SendPro reference-range paging. |
+| `flowmailer_get_message` | Gets one message by id. |
+| `flowmailer_get_message_archive` | Gets archived content metadata for a message. |
+| `flowmailer_get_message_error_archive` | Gets archived error content for a message. |
+| `flowmailer_get_recipient` | Gets recipient information. |
+| `flowmailer_list_resource` | Lists common resources such as flows, templates, sender domains, sources, and stats. |
+
+Write tools, only when `SENDPRO_READ_ONLY=false`:
+
+| Tool | Description |
+| --- | --- |
+| `flowmailer_submit_message` | Submits an email or SMS message. |
+| `flowmailer_simulate_message` | Simulates an email or SMS message. |
+| `flowmailer_resend_message` | Resends a message by id. |
+
+The tool names currently retain the FlowMailer prefix because the public SendPro API and media types still use FlowMailer naming in several places. Package names and documentation use both SendPro and FlowMailer for discoverability.
+
+## Examples
+
+List messages:
+
+```json
+{
+  "method": "GET",
+  "path": "/{account_id}/messages",
+  "matrix": {
+    "daterange": "2026-05-01T00:00:00Z,2026-05-20T00:00:00Z"
+  },
+  "query": {
+    "addevents": true,
+    "sortfield": "INSERTED",
+    "sortorder": "ASC"
+  },
+  "range": "items=:10"
+}
+```
+
+List flows through the convenience tool:
+
+```json
+{
+  "resource": "flows"
+}
+```
+
+Submit a message, only with `SENDPRO_READ_ONLY=false`:
+
+```json
+{
+  "body": {
+    "messageType": "EMAIL",
+    "headerFromAddress": "sender@example.com",
+    "headerToAddress": "recipient@example.com",
+    "subject": "Hello",
+    "text": "Message body"
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+Useful commands:
+
+```bash
+npm run dev
+npm run build
+npm run typecheck
+npm test
+npm run inspect
+```
+
+For repository structure, badges, release hygiene, and maintenance settings, see [docs/repository-health.md](docs/repository-health.md).
+
+## Publishing
+
+This package is published to npm as [sendpro-flowmailer-mcp](https://www.npmjs.com/package/sendpro-flowmailer-mcp), and the repository includes MCP Registry metadata for registry submission.
+
+For npm:
+
+```bash
+npm publish --access public
+```
+
+For the official MCP Registry, publish [server.json](server.json) after the npm package exists. The npm package includes:
+
+```json
+{
+  "mcpName": "io.github.mestika/sendpro-flowmailer-mcp"
+}
+```
+
+## Releases and Versions
+
+This project uses semantic version tags such as `v0.1.0`, `v0.1.1`, and `v1.0.0`.
+
+Use:
+
+```bash
+npm run version:patch  # bug fixes and small documentation-only release updates
+npm run version:minor  # new backwards-compatible tools or features
+npm run version:major  # breaking changes
+git push origin main --follow-tags
+```
+
+Then create a GitHub Release from the new tag. The GitHub Release is the public changelog entry; the Git tag is the exact source snapshot. See [docs/releasing.md](docs/releasing.md) for the full checklist.
+
+## Security
+
+Never commit real SendPro credentials. Use MCP client environment variables, shell environment variables, or a local `.env` file.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and operational notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface FlowMailerConfig {
+    accountId: string;
+    clientId: string;
+    clientSecret: string;
+    readOnly: boolean;
+    apiBaseUrl: string;
+    authBaseUrl: string;
+    apiMediaType: string;
+}
+export type Env = Record<string, string | undefined>;
+export declare function loadConfig(env?: Env): FlowMailerConfig;

package/dist/config.js

@@ -0,0 +1,45 @@
+const ENV_ALIASES = {
+    accountId: ["SENDPRO_ACCOUNT_ID", "SPOTLER_SENDPRO_ACCOUNT_ID", "FLOWMAILER_ACCOUNT_ID"],
+    clientId: ["SENDPRO_CLIENT_ID", "SPOTLER_SENDPRO_CLIENT_ID", "FLOWMAILER_CLIENT_ID"],
+    clientSecret: ["SENDPRO_CLIENT_SECRET", "SPOTLER_SENDPRO_CLIENT_SECRET", "FLOWMAILER_CLIENT_SECRET"],
+    readOnly: ["READ_ONLY", "SENDPRO_READ_ONLY", "SPOTLER_SENDPRO_READ_ONLY", "FLOWMAILER_READ_ONLY"],
+    apiBaseUrl: ["SENDPRO_API_BASE_URL", "SPOTLER_SENDPRO_API_BASE_URL", "FLOWMAILER_API_BASE_URL"],
+    authBaseUrl: ["SENDPRO_AUTH_BASE_URL", "SPOTLER_SENDPRO_AUTH_BASE_URL", "FLOWMAILER_AUTH_BASE_URL"],
+    apiMediaType: ["SENDPRO_API_MEDIA_TYPE", "SPOTLER_SENDPRO_API_MEDIA_TYPE", "FLOWMAILER_API_MEDIA_TYPE"]
+};
+export function loadConfig(env = process.env) {
+    const accountId = readFirst(env, ENV_ALIASES.accountId);
+    const clientId = readFirst(env, ENV_ALIASES.clientId);
+    const clientSecret = readFirst(env, ENV_ALIASES.clientSecret);
+    const missing = [
+        ["account id", ENV_ALIASES.accountId, accountId],
+        ["client id", ENV_ALIASES.clientId, clientId],
+        ["client secret", ENV_ALIASES.clientSecret, clientSecret]
+    ].flatMap(([label, names, value]) => (value ? [] : [`${label}: ${formatAliases(names)}`]));
+    if (missing.length > 0) {
+        throw new Error(`Missing required SendPro environment variables: ${missing.join("; ")}`);
+    }
+    return {
+        accountId: accountId,
+        clientId: clientId,
+        clientSecret: clientSecret,
+        readOnly: parseReadOnly(readFirst(env, ENV_ALIASES.readOnly) ?? "true"),
+        apiBaseUrl: stripTrailingSlash(readFirst(env, ENV_ALIASES.apiBaseUrl) ?? "https://api.flowmailer.net"),
+        authBaseUrl: stripTrailingSlash(readFirst(env, ENV_ALIASES.authBaseUrl) ?? "https://login.flowmailer.net"),
+        apiMediaType: readFirst(env, ENV_ALIASES.apiMediaType) ?? "application/vnd.flowmailer.v1.12+json"
+    };
+}
+function readFirst(env, names) {
+    return names.map((name) => env[name]).find((value) => value !== undefined && value.length > 0);
+}
+function formatAliases(names) {
+    const [primary, ...aliases] = names;
+    return aliases.length === 0 ? primary : `${primary} (aliases: ${aliases.join(", ")})`;
+}
+function parseReadOnly(value) {
+    return !["false", "0", "no", "off"].includes(value.trim().toLowerCase());
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,GAAG;IAClB,SAAS,EAAE,CAAC,oBAAoB,EAAE,4BAA4B,EAAE,uBAAuB,CAAC;IACxF,QAAQ,EAAE,CAAC,mBAAmB,EAAE,2BAA2B,EAAE,sBAAsB,CAAC;IACpF,YAAY,EAAE,CAAC,uBAAuB,EAAE,+BAA+B,EAAE,0BAA0B,CAAC;IACpG,QAAQ,EAAE,CAAC,WAAW,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,sBAAsB,CAAC;IACjG,UAAU,EAAE,CAAC,sBAAsB,EAAE,8BAA8B,EAAE,yBAAyB,CAAC;IAC/F,WAAW,EAAE,CAAC,uBAAuB,EAAE,+BAA+B,EAAE,0BAA0B,CAAC;IACnG,YAAY,EAAE,CAAC,wBAAwB,EAAE,gCAAgC,EAAE,2BAA2B,CAAC;CAC/F,CAAC;AAEX,MAAM,UAAU,UAAU,CAAC,MAAW,OAAO,CAAC,GAAG;IAC/C,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG;QACd,CAAC,YAAY,EAAE,WAAW,CAAC,SAAS,EAAE,SAAS,CAAC;QAChD,CAAC,WAAW,EAAE,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC;QAC7C,CAAC,eAAe,EAAE,WAAW,CAAC,YAAY,EAAE,YAAY,CAAC;KAC1D,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,aAAa,CAAC,KAA0B,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEhH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,mDAAmD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,OAAO;QACL,SAAS,EAAE,SAAmB;QAC9B,QAAQ,EAAE,QAAkB;QAC5B,YAAY,EAAE,YAAsB;QACpC,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC;QACvE,UAAU,EAAE,kBAAkB,CAAC,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,UAAU,CAAC,IAAI,4BAA4B,CAAC;QACtG,WAAW,EAAE,kBAAkB,CAAC,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,IAAI,8BAA8B,CAAC;QAC1G,YAAY,EAAE,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,uCAAuC;KAClG,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,GAAQ,EAAE,KAAwB;IACnD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,SAAS,aAAa,CAAC,KAAwB;IAC7C,MAAM,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC;IACpC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAE,OAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,cAAc,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACpG,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/flowmailer-client.d.ts

@@ -0,0 +1,40 @@
+import type { FlowMailerConfig } from "./config.js";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type ParameterValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
+export interface FlowMailerRequest {
+    method: HttpMethod;
+    path: string;
+    accountId?: string;
+    matrix?: Record<string, ParameterValue>;
+    query?: Record<string, ParameterValue>;
+    body?: unknown;
+    range?: string;
+}
+export interface FlowMailerResponse<T = unknown> {
+    status: number;
+    headers: Record<string, string>;
+    data: T | undefined;
+}
+export declare class ReadOnlyViolationError extends Error {
+    constructor(method: string, path: string);
+}
+export declare class FlowMailerApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly headers: Record<string, string>;
+    constructor(status: number, body: unknown, headers: Record<string, string>);
+}
+export declare class FlowMailerClient {
+    private readonly config;
+    private readonly fetchImpl;
+    private token;
+    constructor(config: FlowMailerConfig, fetchImpl?: typeof fetch);
+    request<T = unknown>(request: FlowMailerRequest): Promise<FlowMailerResponse<T>>;
+    private requestWithToken;
+    private getAccessToken;
+    private buildApiUrl;
+    private resolvePath;
+    private buildApiHeaders;
+    private parseResponse;
+    private assertReadOnlyAllows;
+}

package/dist/flowmailer-client.js

@@ -0,0 +1,191 @@
+export class ReadOnlyViolationError extends Error {
+    constructor(method, path) {
+        super(`READ_ONLY is enabled; refusing ${method.toUpperCase()} ${path}`);
+        this.name = "ReadOnlyViolationError";
+    }
+}
+export class FlowMailerApiError extends Error {
+    status;
+    body;
+    headers;
+    constructor(status, body, headers) {
+        super(`FlowMailer API request failed with status ${status}`);
+        this.status = status;
+        this.body = body;
+        this.headers = headers;
+        this.name = "FlowMailerApiError";
+    }
+}
+export class FlowMailerClient {
+    config;
+    fetchImpl;
+    token;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async request(request) {
+        this.assertReadOnlyAllows(request.method, request.path);
+        const url = this.buildApiUrl(request);
+        return this.requestWithToken(url, request, true);
+    }
+    async requestWithToken(url, request, allowTokenRefreshRetry) {
+        const token = await this.getAccessToken();
+        const response = await this.fetchImpl(url, {
+            method: request.method,
+            headers: this.buildApiHeaders(token, request),
+            body: request.body === undefined ? undefined : JSON.stringify(request.body)
+        });
+        if (response.status === 401 && allowTokenRefreshRetry) {
+            this.token = undefined;
+            return this.requestWithToken(url, request, false);
+        }
+        return this.parseResponse(response);
+    }
+    async getAccessToken() {
+        const now = Date.now();
+        if (this.token && this.token.expiresAt > now) {
+            return this.token.accessToken;
+        }
+        const body = new URLSearchParams({
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+            grant_type: "client_credentials",
+            scope: "api"
+        });
+        const response = await this.fetchImpl(`${this.config.authBaseUrl}/oauth/token`, {
+            method: "POST",
+            headers: {
+                accept: this.config.apiMediaType,
+                "content-type": "application/x-www-form-urlencoded"
+            },
+            body
+        });
+        const parsed = (await readResponseBody(response));
+        if (!response.ok || !parsed?.access_token) {
+            throw new FlowMailerApiError(response.status, parsed, selectedHeaders(response.headers));
+        }
+        const expiresInSeconds = typeof parsed.expires_in === "number" ? parsed.expires_in : 60;
+        this.token = {
+            accessToken: parsed.access_token,
+            expiresAt: now + Math.max(1, expiresInSeconds - 5) * 1000
+        };
+        return this.token.accessToken;
+    }
+    buildApiUrl(request) {
+        const resolvedPath = this.resolvePath(request.path, request.accountId);
+        const matrixPath = appendMatrixParams(resolvedPath, request.matrix);
+        const url = new URL(matrixPath, `${this.config.apiBaseUrl}/`);
+        appendSearchParams(url, request.query);
+        return url.toString();
+    }
+    resolvePath(path, accountId) {
+        if (!path.startsWith("/")) {
+            throw new Error("FlowMailer API path must be a relative path starting with /");
+        }
+        if (path.startsWith("//")) {
+            throw new Error("FlowMailer API path must not be protocol-relative");
+        }
+        return path.replaceAll("{account_id}", encodeURIComponent(accountId ?? this.config.accountId));
+    }
+    buildApiHeaders(token, request) {
+        const headers = {
+            authorization: `Bearer ${token}`,
+            accept: this.config.apiMediaType
+        };
+        if (request.range) {
+            headers.range = request.range;
+        }
+        if (request.body !== undefined) {
+            headers["content-type"] = this.config.apiMediaType;
+        }
+        return headers;
+    }
+    async parseResponse(response) {
+        const headers = selectedHeaders(response.headers);
+        const data = await readResponseBody(response);
+        if (!response.ok) {
+            throw new FlowMailerApiError(response.status, data, headers);
+        }
+        return {
+            status: response.status,
+            headers,
+            data: data
+        };
+    }
+    assertReadOnlyAllows(method, path) {
+        if (this.config.readOnly && method !== "GET") {
+            throw new ReadOnlyViolationError(method, path);
+        }
+    }
+}
+function appendMatrixParams(path, matrix) {
+    if (!matrix) {
+        return path;
+    }
+    const entries = Object.entries(matrix).flatMap(([key, value]) => {
+        const serialized = serializeParameterValue(value);
+        return serialized === undefined ? [] : [[key, serialized]];
+    });
+    if (entries.length === 0) {
+        return path;
+    }
+    const encoded = entries
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join(";");
+    return `${path};${encoded}`;
+}
+function appendSearchParams(url, query) {
+    if (!query) {
+        return;
+    }
+    for (const [key, value] of Object.entries(query)) {
+        const serialized = serializeParameterValue(value);
+        if (serialized !== undefined) {
+            url.searchParams.set(key, serialized);
+        }
+    }
+}
+function serializeParameterValue(value) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0 ? undefined : value.map(String).join(",");
+    }
+    return String(value);
+}
+async function readResponseBody(response) {
+    if (response.status === 204 || response.status === 205) {
+        return undefined;
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+        return undefined;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("json") || /^[\[{]/.test(text.trim())) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function selectedHeaders(headers) {
+    const keep = [
+        "content-range",
+        "content-type",
+        "location",
+        "next-range",
+        "retry-after",
+        "www-authenticate"
+    ];
+    return Object.fromEntries(keep.flatMap((name) => {
+        const value = headers.get(name);
+        return value === null ? [] : [[name, value]];
+    }));
+}
+//# sourceMappingURL=flowmailer-client.js.map

package/dist/flowmailer-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowmailer-client.js","sourceRoot":"","sources":["../src/flowmailer-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";