# @mailto.foo/sdk

The JavaScript SDK for [mailto.foo](https://mailto.foo) — a headless email subscription and contact form service. Drop it in via script tag or npm, hand it your publish key, and it handles bot protection and delivers only verified submissions to your dashboard.

No backend code required on your end.

## Installation

``` bash
npm install @mailto.foo/sdk
```
Or via CDN (no npm needed):
``` html
<script src="https://cdn.jsdelivr.net/npm/@mailto.foo/sdk/dist/sdk.min.js"></script>
```

## Usage

### npm / ESM

```js
import { Mailto } from '@mailto.foo/sdk'

const mailto = new Mailto({ publishKey: 'pk_your_publish_key' })

await mailto.subscribe({ email: 'user@example.com' })
```

### Script tag

The CDN build auto-enhances any `<form>` whose `action` points at your subscribe endpoint — no JavaScript required:

```html
<script src="https://cdn.jsdelivr.net/npm/@mailto.foo/sdk/dist/sdk.min.js"></script>

<form action="https://api.mailto.foo/your_publish_key/subscribe">
  <input type="email" name="email" required>
  <button type="submit">Subscribe</button>
</form>
```

On submit, the SDK intercepts the form, calls `subscribe` with the form fields, resets the form on success, and dispatches `mailto:submitting` / `mailto:success` / `mailto:error` custom events on the form element so you can hook in your own UI:

```js
form.addEventListener('mailto:submitting', () => showLoading())
form.addEventListener('mailto:success', () => showThankYou())
form.addEventListener('mailto:error', (e) => showError(e.detail.error.message))
```

By default the SDK only fires events and resets the form — it does not touch any elements on the page. Add `data-verbose` to the form to opt into automatic UI management:

- It injects a `.mailto-foo-error` and a `.mailto-foo-success` element into the form (if not already present) and fills them with the error or success message on submit.
- Any element matching `.mailto-foo-button`, `button[type="submit"]`, or `input[type="submit"]` is disabled (and gets `data-loading="true"`) while the request is in flight, so you can style a loading state.

```html
<form action="https://api.mailto.foo/your_publish_key/subscribe" data-verbose>
  <input type="email" name="email" required>
  <div class="mailto-foo-error"></div>
  <div class="mailto-foo-success"></div>
  <button type="submit" class="mailto-foo-button">Subscribe</button>
</form>
```

The SDK is also exposed as `window.Mailto` for manual usage:

```js
const mailto = new Mailto({ publishKey: 'pk_your_publish_key' })

await mailto.subscribe({ email: 'user@example.com' })
```

### Error handling

`subscribe` throws an `Error` with the message from the API on failure, so you can catch it directly:

```js
try {
  await mailto.subscribe({ email: 'user@example.com' })
} catch (err) {
  console.error(err.message) // e.g. "Email already subscribed"
}
```

### Publish Key

Your publish key (`pk_xxx`) is tied to your mailto.foo account and the domain you registered. It is safe to expose in frontend code — it only allows submissions, not reads.
Get your publish key from your mailto.foo dashboard.

## AI Setup

If you use an AI coding agent that reads `AGENTS.md`, run:

```bash
npx @mailto.foo/sdk init
```

This writes everything your agent needs to know to wire up subscribe/contact forms into `AGENTS.md` at your project root — creating the file if it doesn't exist, or appending to it if it does.

## License
MIT