@mailto.foo/sdk 1.5.1 → 1.5.2

package/README.md

@@ -87,5 +87,15 @@ try {
 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.
 
+## Claude Code
+
+If you use [Claude Code](https://claude.com/claude-code), run:
+
+```bash
+npx @mailto.foo/sdk init
+```
+
+This adds a `/mailto-foo` slash command to your project (`.claude/commands/mailto-foo.md`) with everything Claude needs to know to wire up subscribe/contact forms with this SDK.
+
 ## License
 MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { copyFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const command = process.argv[2];
+const init = () => {
+    const src = join(__dirname, "..", "commands", "mailto-foo.md");
+    const destDir = join(process.cwd(), ".claude", "commands");
+    const dest = join(destDir, "mailto-foo.md");
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    console.log(`Created ${join(".claude", "commands", "mailto-foo.md")}`);
+    console.log("Run /mailto-foo in Claude Code to integrate @mailto.foo/sdk.");
+};
+switch (command) {
+    case "init":
+        init();
+        break;
+    default:
+        console.log("Usage: npx @mailto.foo/sdk init");
+        process.exit(command === undefined ? 0 : 1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhC,MAAM,IAAI,GAAG,GAAG,EAAE;IACjB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAE5C,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxB,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC;IACvE,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;AAC7E,CAAC,CAAC;AAEF,QAAQ,OAAO,EAAE,CAAC;IACjB,KAAK,MAAM;QACV,IAAI,EAAE,CAAC;QACP,MAAM;IACP;QACC,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/commands/mailto-foo.md

@@ -0,0 +1,97 @@
+---
+description: Integrate @mailto.foo/sdk for email subscription/contact forms
+---
+
+# @mailto.foo/sdk integration
+
+Headless email subscription/contact-form SDK. Two entry points: `src/index.ts` (the `Mailto` class, published as ESM/CJS) and `src/cdn.ts` (auto-enhancement script for the CDN bundle, built on top of `Mailto`).
+
+## Core API
+
+```js
+import { Mailto } from '@mailto.foo/sdk'
+
+const mailto = new Mailto({ publishKey: 'pk_your_publish_key' })
+await mailto.subscribe({ email: 'user@example.com', /* ...any extra string fields */ })
+```
+
+`subscribe(data)` accepts `{ email: string; [key: string]: string }` — `email` is the only required field. Any additional string key/value pairs (name, company, message, plan, source, etc.) are passed straight through to the API and show up alongside the subscriber in the mailto.foo dashboard. There's no schema to register; just add the fields you need to the object (or to the `<form>` as extra `<input name="...">` elements when using the CDN auto-enhancement).
+
+- `subscribe(data)` first calls `GET {API_BASE}/config/:publishKey/config` to fetch publisher config (5s timeout via `AbortController`).
+- If the publisher has `turnstileSiteKey` set, it loads Cloudflare Turnstile, renders an invisible widget, and obtains a token before submitting — falling back to a visible modal overlay if the invisible challenge doesn't resolve to a token. This whole flow is internal; callers don't need to do anything extra.
+- It then `POST`s `{ data, config: { publishKey, token } }` to `{API_BASE}/subscribe`.
+- On a non-OK response it throws an `Error` whose message is the API's `error` field (JSON responses) or raw text body (non-JSON responses).
+- On success it resolves with `void` — there is no return payload to inspect.
+
+`API_BASE` is hardcoded to `https://api-mailto-foo.dan-7bc.workers.dev`.
+
+## CDN auto-enhancement (`src/cdn.ts`)
+
+The CDN bundle scans the DOM for `form[action]` elements whose action matches `/((?:pk_|ph_public_)[A-Za-z0-9_-]+)\/subscribe\/?(?:[?#].*)?$/` and wires each one up automatically — no manual JS needed. Forms pointing at a mailto.foo subscribe path with an unrecognized key prefix have their submit blocked (with a `console.warn`) instead of letting the browser navigate to a 404.
+
+1. Calls `mailto.injectHoneypot(form)` (see Bot protection below) before attaching the submit handler.
+2. Intercepts `submit`, calls `preventDefault()`.
+3. Disables and marks loading (`data-loading="true"`) on every element matching `.mailto-foo-button`, `button[type="submit"]`, or `input[type="submit"]`.
+4. Dispatches `mailto:submitting` (bubbling `CustomEvent`, no detail) on the form.
+5. Calls `mailto.subscribe()` with all form fields collected via `FormData` — including any extra fields you've added (see "Extra/custom fields" above) and the injected honeypot field.
+6. On success: resets the form, dispatches `mailto:success`. If `data-verbose` is present, also clears `.mailto-foo-error` and sets `.mailto-foo-success` text to "Thanks for subscribing!".
+7. On failure: dispatches `mailto:error` with `detail: { error: <Error> }`. If `data-verbose` is present, also clears `.mailto-foo-success` and sets `.mailto-foo-error` text to `err.message`.
+8. Always re-enables buttons in a `finally` block (only if `data-verbose`).
+
+By default the CDN script is **silent** — it only fires events and resets the form; it does not touch any status elements or button states. Add `data-verbose` to the `<form>` to opt into automatic UI management: status `<div>`s are auto-created if absent (appended as the last children), buttons are disabled during submission, and success/error text is written automatically. Exposes `window.Mailto = Mailto`.
+
+```html
+<!-- Default: silent mode — only events fire, no automatic UI changes -->
+<form action="https://api.mailto.foo/pk_xxx/subscribe">
+  <input type="email" name="email" required>
+  <button type="submit">Subscribe</button>
+</form>
+
+<script>
+form.addEventListener('mailto:submitting', () => showLoading())
+form.addEventListener('mailto:success', () => showThankYou())
+form.addEventListener('mailto:error', (e) => showError(e.detail.error.message))
+</script>
+
+<!-- data-verbose: auto-manages status divs and button loading state -->
+<form action="https://api.mailto.foo/pk_xxx/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>
+```
+
+## Bot protection / honeypot
+
+`Mailto#injectHoneypot(form)` fetches `GET {API_BASE}/config/:publishKey/hint?fields=<comma-separated existing field names>` and, if the publisher has it enabled, appends a hidden `<input>` (visually hidden, `tabindex="-1"`, `aria-hidden="true"`, `autocomplete="off"`) to the form using a field name returned by the API. The returned `field` name and an optional `sessionId` are cached on the `Mailto` instance and sent as `f` / `sid` on the next `subscribe()` call.
+
+- The CDN auto-enhancement calls this automatically for every enhanced form — no setup needed.
+- For manual/headless usage, call `await mailto.injectHoneypot(form)` once before the form can be submitted if you want this protection (then call `subscribe()` as usual — the honeypot field will be included via `FormData`/your data object).
+- Don't strip unexpected hidden input fields from a mailto.foo form — they may be the honeypot field used for bot detection.
+
+## Error handling
+
+Always wrap manual `subscribe()` calls in try/catch — it throws a plain `Error`:
+
+```js
+try {
+  await mailto.subscribe({ email })
+} catch (err) {
+  console.error(err.message) // e.g. "Email already subscribed"
+}
+```
+
+## Gotchas / non-obvious details
+
+- The publish key (`pk_xxx`) is meant to be exposed client-side — it only authorizes submissions, not reads.
+- `subscribe()` makes **two** network round-trips per call: a config fetch, then the actual subscribe POST (plus a Turnstile challenge round-trip when bot protection is enabled). Don't assume it's a single fetch when debugging latency or mocking requests in tests.
+- Turnstile script loading is memoized via the module-level `turnstileScriptPromise` — it's only ever injected once per page, even across multiple forms/instances.
+- The form-action regex requires the action URL to end in `/<publishKey>/subscribe` (optionally with a trailing slash or query/hash) and the key to start with `pk_` or `ph_public_` — forms with other URL shapes are silently skipped, but forms pointing at *some* `<key>/subscribe` path on a mailto.foo host with an unrecognized prefix have submission blocked with a console warning.
+- Extra form fields beyond `email` are passed straight through to the API as arbitrary string key/value pairs (`SubscribeData` is `{ email: string; [key: string]: string }`).
+
+## Task
+
+$ARGUMENTS
+
+Use the reference above to add or debug a mailto.foo subscribe/contact form in this project.

package/package.json

@@ -2,9 +2,12 @@
   "name": "@mailto.foo/sdk",
   "type": "module",
   "description": "Headless email subscription and contact form SDK for mailto.foo",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "sdk": "./dist/bin/cli.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://gitlab.com/mailto.foo/sdk.git"
@@ -19,6 +22,7 @@
     "@biomejs/biome": "1.8.3",
     "@changesets/cli": "^2.27.7",
     "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^25.9.3",
     "esbuild": "^0.28.0",
     "typescript": "^5.5.3"
   },
@@ -26,8 +30,9 @@
     "url": "https://gitlab.com/mailto.foo/sdk/-/boards"
   },
   "scripts": {
-    "build": "tsc && pnpm run build:cdn",
+    "build": "tsc && pnpm run build:cdn && pnpm run build:commands && chmod +x dist/bin/cli.js",
     "build:cdn": "esbuild src/cdn.ts --bundle --minify --format=iife --outfile=dist/sdk.min.js",
+    "build:commands": "mkdir -p dist/commands && cp src/commands/mailto-foo.md dist/commands/mailto-foo.md",
     "check": "biome check --write ./src",
     "workflow:check": "biome check ./src",
     "release": "pnpm run build && changeset publish"