Add a provider

Choose the stable business contract#

Start with what the product needs, not what a vendor SDK exposes. Mail needs rendered delivery. Payments need checkout, customer management, and verified events. Storage needs put, get, delete, and list.

Extend the provider name#

Add the new provider identifier to the typed union in src/config/types.ts or the module-local contract.

export type MailProviderName =
  | 'resend'
  | 'cloudflare'
  | 'ses'
  | 'new-provider'

Implement the adapter#

Keep authentication, endpoints, SDK calls, response parsing, and vendor error translation in one small file.

export const newProvider: MailProvider = {
  async send(message) {
    // Translate the stable message into the vendor protocol.
  },
}

Register the factory#

Map configuration to the adapter in the module registry. Routes and product components must not change.

Add configuration and documentation#

• Add variable names to .env.example.
• Parse server-only secrets in the environment module.
• Document required permissions, webhook URLs, sender identities, or product IDs.
• Keep generated production previews disabled.

Close the workflow#

Add unit tests for signing, parsing, or normalization. Add E2E preview behavior if external credentials cannot exist in CI. Finally, exercise the real production provider through the user workflow.