npm package: @purplebird/mailer-client
Description: Client-side integration package for Purple Bird Mailer API
Author: Purple Bird Agency
Latest version: 1.1.1

# @purplebird/mailer-client

Client-side integration package for Purple Bird Mailer API. This package provides utilities for handling form submissions to the Purple Bird Mailer API via Netlify Functions.

## Installation

```bash
npm install @purplebird/mailer-client
```

## Usage

### Form Helper (Client-side)

```javascript
import { submitMailerForm, initMailerForm } from '@purplebird/mailer-client';

// Option 1: Manual submission
const form = document.querySelector('#contact-form');
await submitMailerForm(form, {
  endpoint: '/.netlify/functions/submit-contact',
  onSuccess: (result) => console.log('Success!', result),
  onError: (error) => console.error('Error:', error)
});

// Option 2: Auto-initialize form handler
initMailerForm('#contact-form', {
  endpoint: '/.netlify/functions/submit-contact',
  successMessage: '#success-message',
  errorMessage: '#error-message',
  onSubmitButton: '#submit-button'
});
```

### Netlify Function (Server-side)

The `netlify-function.js` file should be deployed as a Netlify Function. It handles form submissions and forwards them to the Purple Bird Mailer API.

Create your Netlify function using the `createMailerHandler()` factory function with explicit configuration:

```javascript
// netlify/functions/submit-contact.js
const { createMailerHandler } = require('@purplebird/mailer-client/netlify-function');

exports.handler = createMailerHandler({
  baseUrl: process.env.MAILER_BASE_URL || 'https://mailer.purplebird.agency/api',
  formId: process.env.MAILER_FORM_ID, // Form-specific ID
  apiKey: process.env.MAILER_API_KEY, // Client-level API key (works for all forms)
  debug: process.env.NODE_ENV !== 'production'
});
```

**Environment Variables:**
- `MAILER_BASE_URL` - Base URL of the mailer API
- `MAILER_FORM_ID` - Form ID (unique per form)
- `MAILER_API_KEY` - Client-level API key (same key for all forms on your website)

**Configuration Options:**
- `baseUrl` (required) - Base URL of the Purple Bird Mailer API (e.g., `https://mailer.purplebird.agency/api`)
- `formId` (required) - Your form ID (identifies which form is being submitted)
- `apiKey` (required) - Your client-level API key for authentication (one key works for all forms on your website)
- `debug` (optional) - Enable debug logging (default: `false`)

**Important Notes:**
- **Client-Level API Keys**: One API key per client/website works for all forms belonging to that client
- Each form still needs its own `formId` to identify which form configuration to use
- Set `MAILER_API_KEY` in your Netlify environment variables (not `MAILER_FORM_API_KEY`)

**Benefits of explicit configuration:**
- Makes dependencies explicit and easier to test
- Allows multiple instances with different configurations
- Works better in different deployment environments
- No hidden environment variable dependencies

## Features

- ✅ Form submission handling
- ✅ File upload support
- ✅ Honeypot spam protection
- ✅ Rate limiting
- ✅ Error handling
- ✅ Success/error callbacks
- ✅ Automatic form state management

## Peer Dependencies

This package requires the following peer dependency (for the Netlify function):

- `busboy` (^1.6.0)

## License

MIT

## Publishing

This package uses GitHub Actions for automated publishing to npm. To publish a new version:

### Setup (One-time)

1. Create an npm access token with publish permissions:
   - Go to https://www.npmjs.com/settings/[your-username]/tokens
   - Create a new "Automation" token
   - Copy the token

2. Add the token as a GitHub secret:
   - Go to your repository settings → Secrets and variables → Actions
   - Add a new secret named `NPM_TOKEN` with your npm token value

### Publishing a New Version

**Option 1: Using npm scripts (recommended)**
```bash
# Patch version (1.0.0 → 1.0.1)
npm run version:patch

# Minor version (1.0.0 → 1.1.0)
npm run version:minor

# Major version (1.0.0 → 2.0.0)
npm run version:major
```

These scripts will:
- Update `package.json` version
- Create a git commit and tag (e.g., `v1.0.1`)
- Push to GitHub
- Trigger the GitHub Action to publish to npm

**Note:** The workflow automatically checks if a version already exists on npm and will skip publishing if it does (to prevent errors). Always bump the version before publishing.

**Option 2: Manual tagging**
```bash
# Update version in package.json manually, then:
git add package.json
git commit -m "chore: bump version to 1.0.1"
git tag v1.0.1
git push origin main --tags
```

**Option 3: Manual publish (for testing)**
```bash
npm publish --access public
```

## Repository

https://github.com/purplebird-agency/purplebird-mailer-client