@webamoki/web-svelte 0.7.0 → 0.7.1

package/dist/utils/email/README.md

@@ -0,0 +1,209 @@
+# Email Utility Package
+
+This package provides utilities for sending emails using AWS Simple Email Service (SES).
+
+## Installation
+
+The AWS SES SDK is already included as a dependency. You'll need to configure your AWS credentials and region.
+
+## Configuration
+
+### Environment Variables
+
+The email utility requires the following environment variables:
+
+- `AWS_REGION` - AWS region where SES is configured (e.g., `us-east-1`)
+- `AWS_ACCESS_KEY_ID` - AWS access key ID
+- `AWS_SECRET_ACCESS_KEY` - AWS secret access key
+
+### SES Setup
+
+Before using this utility, ensure:
+
+1. Your AWS account has SES enabled in your chosen region
+2. Your sender email address(es) are verified in SES
+3. If in SES sandbox mode, recipient addresses must also be verified
+4. Your account has the necessary IAM permissions to send emails via SES
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { sendEmail } from '@webamoki/web-svelte/utils/email';
+
+// Send a simple text email
+const messageId = await sendEmail({
+	to: 'recipient@example.com',
+	subject: 'Hello from SES',
+	text: 'This is a plain text email.',
+	from: 'sender@example.com'
+});
+
+console.log('Email sent with message ID:', messageId);
+```
+
+### HTML Email
+
+```typescript
+await sendEmail({
+	to: 'recipient@example.com',
+	subject: 'Welcome!',
+	html: '<h1>Welcome to our service!</h1><p>Thanks for signing up.</p>',
+	text: 'Welcome to our service! Thanks for signing up.', // Fallback for email clients that don't support HTML
+	from: 'noreply@example.com',
+	fromName: 'My Application'
+});
+```
+
+### Multiple Recipients
+
+```typescript
+await sendEmail({
+	to: ['user1@example.com', 'user2@example.com'],
+	cc: 'manager@example.com',
+	bcc: ['archive@example.com', 'backup@example.com'],
+	subject: 'Team Update',
+	text: 'This is a team-wide announcement.',
+	from: 'team@example.com'
+});
+```
+
+### With Reply-To
+
+```typescript
+await sendEmail({
+	to: 'customer@example.com',
+	subject: 'Your order confirmation',
+	html: '<p>Your order has been confirmed!</p>',
+	from: 'noreply@example.com',
+	fromName: 'Order System',
+	replyTo: 'support@example.com'
+});
+```
+
+## API Reference
+
+### `sendEmail(options: SendEmailOptions): Promise<string>`
+
+Sends an email via AWS SES.
+
+**Returns:** Promise that resolves to the SES message ID (string) on success.
+
+**Throws:** Error with descriptive message if:
+
+- Validation fails (missing required fields, invalid recipients, etc.)
+- AWS SES returns an error (credentials, permissions, service issues)
+- SES response does not contain a MessageId (unlikely but handled explicitly)
+
+### `SendEmailOptions`
+
+```typescript
+interface SendEmailOptions {
+	to: string | string[]; // Required: recipient email address(es)
+	cc?: string | string[]; // Optional: CC recipients
+	bcc?: string | string[]; // Optional: BCC recipients
+	subject: string; // Required: email subject
+	text?: string; // Optional: plain text body
+	html?: string; // Optional: HTML body
+	from: string; // Required: sender email
+	fromName?: string; // Optional: sender display name
+	replyTo?: string | string[]; // Optional: reply-to address(es)
+}
+```
+
+## Error Handling
+
+The `sendEmail` function validates inputs and will throw errors for:
+
+- Missing required fields (`to`, `from`, `subject`, at least one of `text` or `html`)
+- Empty recipient list (no valid email addresses after filtering)
+- AWS SES errors (credentials, permissions, service issues)
+
+**Note:** The function automatically filters out empty strings and whitespace-only values from recipient arrays (`to`, `cc`, `bcc`, `replyTo`). For example, `['', 'valid@example.com', '  ']` will be processed as `['valid@example.com']`.
+
+Always wrap calls in try-catch:
+
+```typescript
+try {
+	const messageId = await sendEmail({
+		to: 'user@example.com',
+		subject: 'Test',
+		text: 'Hello!',
+		from: 'sender@example.com'
+	});
+	console.log('Success:', messageId);
+} catch (error) {
+	console.error('Failed to send email:', error.message);
+	// Handle error appropriately
+}
+```
+
+## SvelteKit Integration
+
+### Server-Only Usage
+
+⚠️ **Important:** This utility should only be used in server-side code (e.g., `+page.server.ts`, `+server.ts`, or server-side functions) as it requires AWS credentials.
+
+### Example: Contact Form Handler
+
+```typescript
+// src/routes/contact/+page.server.ts
+import { sendEmail } from '@webamoki/web-svelte/utils/email';
+import type { Actions } from './$types';
+
+export const actions: Actions = {
+	default: async ({ request }) => {
+		const formData = await request.formData();
+		const email = formData.get('email') as string;
+		const message = formData.get('message') as string;
+
+		try {
+			await sendEmail({
+				to: 'admin@example.com',
+				subject: `Contact form submission from ${email}`,
+				text: message,
+				from: 'noreply@example.com',
+				replyTo: email
+			});
+
+			return { success: true };
+		} catch (error) {
+			console.error('Email error:', error);
+			return { success: false, error: 'Failed to send message' };
+		}
+	}
+};
+```
+
+## Best Practices
+
+1. **Never expose AWS credentials in client-side code**
+2. **Use environment variables for configuration**
+3. **Verify sender addresses in SES before deploying**
+4. **Always provide both `text` and `html` versions when sending HTML emails**
+5. **Handle errors gracefully and log failures for monitoring**
+6. **Consider rate limits** - SES has sending limits based on your account status
+7. **Use BCC for bulk emails** to avoid exposing all recipients
+8. **Set appropriate Reply-To addresses** for better user experience
+
+## Troubleshooting
+
+### "Sender not verified" error
+
+Verify your sender email address in the AWS SES console for your region.
+
+### "Access Denied" error
+
+Ensure your AWS credentials have the `ses:SendEmail` permission.
+
+### Emails not arriving
+
+- Check SES sending statistics in AWS console
+- Verify you're not in sandbox mode (or that recipients are verified)
+- Check spam folders
+- Review bounce and complaint notifications in SES
+
+## License
+
+MIT

package/dist/utils/email/index.d.ts

@@ -0,0 +1 @@
+export { sendEmail, type SendEmailOptions } from './ses.js';

package/dist/utils/email/index.js

@@ -0,0 +1 @@
+export { sendEmail } from './ses.js';

package/dist/utils/email/ses.d.ts

@@ -0,0 +1,22 @@
+export interface SendEmailOptions {
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    from: string;
+    fromName?: string;
+    replyTo?: string | string[];
+}
+/**
+ * Send an email using AWS SES.
+ *
+ * Environment variables required:
+ * - AWS_REGION
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ *
+ * @returns messageId returned by SES
+ */
+export declare function sendEmail(options: SendEmailOptions): Promise<string>;

package/dist/utils/email/ses.js

@@ -0,0 +1,95 @@
+import { SESClient, SendEmailCommand } from '@aws-sdk/client-ses';
+// Create SES client once at module level for reuse across function calls
+const sesClient = new SESClient({ region: process.env.AWS_REGION });
+/**
+ * Send an email using AWS SES.
+ *
+ * Environment variables required:
+ * - AWS_REGION
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ *
+ * @returns messageId returned by SES
+ */
+export async function sendEmail(options) {
+    if (!options)
+        throw new Error('sendEmail: options is required');
+    const { to, cc, bcc, subject, text, html, from, fromName, replyTo } = options;
+    if (!subject) {
+        throw new Error('sendEmail: subject is required');
+    }
+    if (!text && !html) {
+        throw new Error('sendEmail: at least one of text or html body must be provided');
+    }
+    if (!from) {
+        throw new Error('sendEmail: sender `from` is required');
+    }
+    // Normalize and validate addresses: convert to array and filter out empty/whitespace strings
+    const normalizeAddresses = (addr) => {
+        if (addr === undefined)
+            return undefined;
+        const addresses = Array.isArray(addr) ? addr : [addr];
+        const filtered = addresses.filter((a) => a && a.trim() !== '');
+        return filtered.length > 0 ? filtered : undefined;
+    };
+    const toAddresses = normalizeAddresses(to);
+    const ccAddresses = normalizeAddresses(cc);
+    const bccAddresses = normalizeAddresses(bcc);
+    const replyToAddresses = normalizeAddresses(replyTo);
+    if (!toAddresses || toAddresses.length === 0) {
+        throw new Error('sendEmail: at least one valid recipient is required (to)');
+    }
+    // Format source with optional fromName
+    const source = fromName ? `${fromName} <${from}>` : from;
+    // Build message body
+    const Message = {
+        Subject: {
+            Charset: 'UTF-8',
+            Data: subject
+        },
+        Body: {}
+    };
+    if (html) {
+        Message.Body.Html = {
+            Charset: 'UTF-8',
+            Data: html
+        };
+    }
+    if (text) {
+        Message.Body.Text = {
+            Charset: 'UTF-8',
+            Data: text
+        };
+    }
+    const params = {
+        Source: source,
+        Destination: {
+            ToAddresses: toAddresses,
+            CcAddresses: ccAddresses,
+            BccAddresses: bccAddresses
+        },
+        Message,
+        ReplyToAddresses: replyToAddresses
+    };
+    try {
+        const command = new SendEmailCommand(params);
+        const res = await sesClient.send(command);
+        if (!res.MessageId) {
+            throw new Error('sendEmail: SES response did not contain a MessageId');
+        }
+        return res.MessageId;
+    }
+    catch (err) {
+        // Normalize error for callers
+        const message = err instanceof Error ? err.message : String(err);
+        let code;
+        if (err && typeof err === 'object') {
+            const e = err;
+            if (typeof e['name'] === 'string')
+                code = e['name'];
+        }
+        const details = { message, code };
+        // Re-throw a clear error for the caller to handle
+        throw new Error(`sendEmail: failed to send email: ${JSON.stringify(details)}`);
+    }
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.7.0",
+  "version": "0.7.1",
   "license": "MIT",
   "files": [
     "dist",
@@ -43,6 +43,10 @@
       "types": "./dist/utils/form/index.d.ts",
       "import": "./dist/utils/form/index.js"
     },
+    "./utils/email": {
+      "types": "./dist/utils/email/index.d.ts",
+      "import": "./dist/utils/email/index.js"
+    },
     "./server/form-handler": {
       "types": "./dist/server/form-handler.d.ts",
       "import": "./dist/server/form-handler.js"
@@ -102,6 +106,7 @@
     "svelte"
   ],
   "dependencies": {
+    "@aws-sdk/client-ses": "^3.948.0",
     "@internationalized/date": "^3.10.0",
     "@lucide/svelte": "^0.553.0",
     "@sveltejs/adapter-auto": "^7.0.0",