@stacksjs/email 0.75.72 → 0.75.73

package/dist/drivers/mailtrap.d.ts

@@ -1,6 +1,26 @@
 import { BaseEmailDriver } from './base';
 import type { EmailMessage, EmailResult } from '@stacksjs/types';
 import type { TemplateOptions } from '../template';
+/**
+ * Where a send goes.
+ *
+ * Mailtrap has two APIs that differ in exactly this: the sandbox captures
+ * mail into a testing inbox and needs that inbox's id in the path, the
+ * Sending API delivers it and takes no inbox at all. The driver used to
+ * default to the sandbox and require an inbox id, so an app that configured
+ * Mailtrap for production could not send through it, and one that left
+ * `MAILTRAP_HOST` unset did not get the default either: `config/services.ts`
+ * sets it to `''`, which `??` keeps, and the request went to `/<inbox id>`.
+ *
+ * So the inbox id decides: with one, the sandbox inbox; without one, real
+ * delivery. `MAILTRAP_HOST` still overrides the host either way (a bulk
+ * stream, a proxy).
+ */
+export declare function mailtrapEndpoint(options: { host?: unknown, inboxId?: unknown }): string;
+/** Mailtrap's Email Sending API: real delivery, no inbox in the path. */
+export declare const MAILTRAP_SENDING_URL: 'https://send.api.mailtrap.io/api/send';
+/** Mailtrap's Email Testing (sandbox) API: captures into an inbox, delivers nothing. */
+export declare const MAILTRAP_SANDBOX_URL: 'https://sandbox.api.mailtrap.io/api/send';
 export declare class MailtrapDriver extends BaseEmailDriver {
   name: string;
   send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;

package/dist/drivers/mailtrap.js

@@ -1 +1 @@
-import{Buffer}from"node:buffer";import{config}from"@stacksjs/config";import{log}from"@stacksjs/logging";import{templateByName}from"../template";import{filterStringHeaders}from"../validation";import{BaseEmailDriver}from"./base";export class MailtrapDriver extends BaseEmailDriver{name="mailtrap";host=null;token=null;inboxId=null;getConfig(){if(this.host===null||this.token===null||this.inboxId===null){this.host=config.services.mailtrap?.host??"https://sandbox.api.mailtrap.io/api/send";this.token=config.services.mailtrap?.token??"";this.inboxId=config.services.mailtrap?.inboxId?Number(config.services.mailtrap.inboxId):void 0}return{host:this.host,token:this.token,inboxId:this.inboxId}}async send(message,options){const{inboxId}=this.getConfig(),logContext={provider:this.name,to:message.to,subject:message.subject,inboxId};log.info("Sending email via Mailtrap...",logContext);try{this.validateMessage(message);let templ;if(message.template)templ=await templateByName(message.template,options);const htmlContent=templ?.html||message.html,replyTo=this.firstMailtrapAddress(message.replyTo),customHeaders=filterStringHeaders(message.headers),mailtrapPayload={from:{email:message.from?.address||config.email.from?.address||"",name:message.from?.name||config.email.from?.name},to:this.formatMailtrapAddresses(message.to),...message.cc&&{cc:this.formatMailtrapAddresses(message.cc)},...message.bcc&&{bcc:this.formatMailtrapAddresses(message.bcc)},...replyTo?{reply_to:replyTo}:{},...customHeaders?{headers:customHeaders}:{},subject:message.subject,...htmlContent&&{html:htmlContent},...message.text&&{text:message.text},...message.attachments&&{attachments:message.attachments.map((attachment)=>({filename:attachment.filename,content:typeof attachment.content==="string"?attachment.content:this.arrayBufferToBase64(attachment.content),type:attachment.contentType||"application/octet-stream"}))}},response=await this.sendWithRetry(mailtrapPayload);return this.handleSuccess(message,response.message_ids?.[0])}catch(error){return this.handleError(error,message)}}formatMailtrapAddresses(addresses){if(!addresses)return[];if(typeof addresses==="string")return[{email:addresses}];return addresses.map((addr)=>{if(typeof addr==="string")return{email:addr};return{email:addr.address,...addr.name&&{name:addr.name}}})}firstMailtrapAddress(value){if(!value)return;if(typeof value==="string")return{email:value};if(Array.isArray(value)){const first=value[0];if(first===void 0)return;if(typeof first==="string")return{email:first};return{email:first.address,...first.name&&{name:first.name}}}return{email:value.address,...value.name&&{name:value.name}}}arrayBufferToBase64(buffer){let binary="";const bytes=new Uint8Array(buffer),len=bytes.byteLength;for(let i=0;i<len;i++)binary+=String.fromCharCode(bytes[i]??0);return typeof btoa==="function"?btoa(binary):Buffer.from(binary).toString("base64")}async sendWithRetry(payload,attempt=1){const{host,token,inboxId}=this.getConfig();if(!inboxId)throw Error("Mailtrap inbox ID is required but not provided. Please set MAILTRAP_INBOX_ID in your environment variables.");const endpoint=`${host}/${inboxId}`;try{const response=await fetch(endpoint,{method:"POST",headers:{Authorization:`Bearer ${token}`,"Content-Type":"application/json"},body:JSON.stringify(payload)});if(!response.ok){const errorData=await response.json();throw Error(`Mailtrap API error: ${response.status} - ${JSON.stringify(errorData)}`)}const data=await response.json();log.info(`[${this.name}] Email sent successfully`,{attempt,messageId:data.message_ids?.[0]});return data}catch(error){if(attempt<(config.services.mailtrap?.maxRetries??3)){const retryTimeout=config.services.mailtrap?.retryTimeout??1000;log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.mailtrap?.maxRetries??3})`);await new Promise((resolve)=>setTimeout(resolve,retryTimeout));return this.sendWithRetry(payload,attempt+1)}throw error}}}export default MailtrapDriver;
+import{Buffer}from"node:buffer";import{config}from"@stacksjs/config";import{log}from"@stacksjs/logging";import{templateByName}from"../template";import{filterStringHeaders}from"../validation";import{BaseEmailDriver}from"./base";export const MAILTRAP_SENDING_URL="https://send.api.mailtrap.io/api/send",MAILTRAP_SANDBOX_URL="https://sandbox.api.mailtrap.io/api/send";function present(value){const text=value==null?"":String(value).trim();return text?text:void 0}export function mailtrapEndpoint(options){const host=present(options.host)?.replace(/\/+$/,""),inboxId=present(options.inboxId);if(inboxId)return`${host??MAILTRAP_SANDBOX_URL}/${encodeURIComponent(inboxId)}`;if(host&&/sandbox\.api\.mailtrap\.io/i.test(host))throw Error("MAILTRAP_HOST points at the Mailtrap sandbox, which needs MAILTRAP_INBOX_ID. Set the inbox id to capture mail for testing, or unset MAILTRAP_HOST to deliver it.");return host??MAILTRAP_SENDING_URL}export class MailtrapDriver extends BaseEmailDriver{name="mailtrap";getConfig(){const mailtrap=config.services.mailtrap,token=present(mailtrap?.token);if(!token)throw Error("Mailtrap API token is required but not provided. Please set MAILTRAP_TOKEN in your environment variables.");return{endpoint:mailtrapEndpoint({host:mailtrap?.host,inboxId:mailtrap?.inboxId}),token,inboxId:present(mailtrap?.inboxId)}}async send(message,options){const inboxId=present(config.services.mailtrap?.inboxId),logContext={provider:this.name,to:message.to,subject:message.subject,inboxId};log.info("Sending email via Mailtrap...",logContext);try{this.validateMessage(message);let templ;if(message.template)templ=await templateByName(message.template,options);const htmlContent=templ?.html||message.html,replyTo=this.firstMailtrapAddress(message.replyTo),customHeaders=filterStringHeaders(message.headers),mailtrapPayload={from:{email:message.from?.address||config.email.from?.address||"",name:message.from?.name||config.email.from?.name},to:this.formatMailtrapAddresses(message.to),...message.cc&&{cc:this.formatMailtrapAddresses(message.cc)},...message.bcc&&{bcc:this.formatMailtrapAddresses(message.bcc)},...replyTo?{reply_to:replyTo}:{},...customHeaders?{headers:customHeaders}:{},subject:message.subject,...htmlContent&&{html:htmlContent},...message.text&&{text:message.text},...message.attachments&&{attachments:message.attachments.map((attachment)=>({filename:attachment.filename,content:typeof attachment.content==="string"?attachment.content:this.arrayBufferToBase64(attachment.content),type:attachment.contentType||"application/octet-stream"}))}},response=await this.sendWithRetry(mailtrapPayload);return this.handleSuccess(message,response.message_ids?.[0])}catch(error){return this.handleError(error,message)}}formatMailtrapAddresses(addresses){if(!addresses)return[];if(typeof addresses==="string")return[{email:addresses}];return addresses.map((addr)=>{if(typeof addr==="string")return{email:addr};return{email:addr.address,...addr.name&&{name:addr.name}}})}firstMailtrapAddress(value){if(!value)return;if(typeof value==="string")return{email:value};if(Array.isArray(value)){const first=value[0];if(first===void 0)return;if(typeof first==="string")return{email:first};return{email:first.address,...first.name&&{name:first.name}}}return{email:value.address,...value.name&&{name:value.name}}}arrayBufferToBase64(buffer){let binary="";const bytes=new Uint8Array(buffer),len=bytes.byteLength;for(let i=0;i<len;i++)binary+=String.fromCharCode(bytes[i]??0);return typeof btoa==="function"?btoa(binary):Buffer.from(binary).toString("base64")}async sendWithRetry(payload,attempt=1){const{endpoint,token}=this.getConfig();try{const response=await fetch(endpoint,{method:"POST",headers:{Authorization:`Bearer ${token}`,"Content-Type":"application/json"},body:JSON.stringify(payload)});if(!response.ok){const errorData=await response.json().catch(()=>({})),err=Error(`Mailtrap API error: ${response.status} - ${JSON.stringify(errorData)}`);err.status=response.status;throw err}const data=await response.json();log.info(`[${this.name}] Email sent successfully`,{attempt,messageId:data.message_ids?.[0]});return data}catch(error){const status=error?.status,nonRetryable=typeof status==="number"&&status>=400&&status<500&&status!==429,maxRetries=config.services.mailtrap?.maxRetries??3;if(!nonRetryable&&attempt<maxRetries){const retryTimeout=config.services.mailtrap?.retryTimeout??1000;log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${maxRetries})`);await new Promise((resolve)=>setTimeout(resolve,retryTimeout));return this.sendWithRetry(payload,attempt+1)}throw error}}}export default MailtrapDriver;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/email",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.72",
+  "version": "0.75.73",
   "description": "The Stacks Email integration. Painlessly create & manage your inboxes, templates, and send emails.",
   "author": "Chris Breuer",
   "contributors": [
@@ -61,26 +61,26 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.75.72",
-    "@stacksjs/database": "0.75.72",
-    "@stacksjs/events": "0.75.72",
-    "@stacksjs/logging": "0.75.72",
+    "@stacksjs/config": "0.75.73",
+    "@stacksjs/database": "0.75.73",
+    "@stacksjs/events": "0.75.73",
+    "@stacksjs/logging": "0.75.73",
     "@stacksjs/mail": "^0.3.11",
-    "@stacksjs/path": "0.75.72",
-    "@stacksjs/storage": "0.75.72",
-    "@stacksjs/strings": "0.75.72",
-    "@stacksjs/stx": "^0.2.359",
-    "@stacksjs/ts-cloud": "^0.16.25",
-    "@stacksjs/utils": "0.75.72"
+    "@stacksjs/path": "0.75.73",
+    "@stacksjs/storage": "0.75.73",
+    "@stacksjs/strings": "0.75.73",
+    "@stacksjs/stx": "^0.2.374",
+    "@stacksjs/ts-cloud": "^0.16.39",
+    "@stacksjs/utils": "0.75.73"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.75.72",
-    "@stacksjs/error-handling": "0.75.72",
-    "@stacksjs/types": "0.75.72",
+    "@stacksjs/cli": "0.75.73",
+    "@stacksjs/error-handling": "0.75.73",
+    "@stacksjs/types": "0.75.73",
     "better-dx": "^0.2.24"
   },
   "peerDependencies": {
-    "@stacksjs/queue": "0.75.72"
+    "@stacksjs/queue": "0.75.73"
   },
   "peerDependenciesMeta": {
     "@stacksjs/queue": {