@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

npm install @purplebird/mailer-client

Usage

Form Helper (Client-side)

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:

// 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)

# 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

# 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)

npm publish --access public

Repository

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