@webamoki/web-svelte 0.6.3 → 0.7.1

package/dist/components/form/Form.svelte

@@ -1,74 +1,3 @@
-<!-- <script lang="ts" generics="S extends type.Any<Record<string, unknown>>">
-	import { toast } from 'svelte-sonner';
-	import { dateTransport } from '../../utils/index.js';
-	import { type } from 'arktype';
-	import type { Snippet } from 'svelte';
-	import type { Readable } from 'svelte/store';
-	import { defaults, superForm, type SuperForm, type SuperValidated } from 'sveltekit-superforms';
-	import { arktype, arktypeClient } from 'sveltekit-superforms/adapters';
-	import type { SuperFormData, SuperFormErrors } from 'sveltekit-superforms/client';
-
-	interface Props {
-		validated?: SuperValidated<S['infer']> | S['infer'];
-		schema: S;
-		onSuccess?: (
-			form: Readonly<SuperValidated<S['infer'], App.Superforms.Message, S['infer']>>
-		) => void;
-		invalidateAll?: boolean;
-		children: Snippet<
-			[
-				{
-					form: SuperForm<S['infer'], App.Superforms.Message>;
-					data: SuperFormData<S['infer']>;
-					delayed: Readable<boolean>;
-					errors: SuperFormErrors<S['infer']>;
-				}
-			]
-		>;
-		// TODO: Enforce use of resolve
-		action: string;
-		actionName?: string;
-		class?: string;
-	}
-
-	let {
-		validated: _validated,
-		schema,
-		onSuccess,
-		invalidateAll = false,
-		children,
-		action: _action,
-		actionName,
-		class: className
-	}: Props = $props();
-
-	let validated = _validated ?? defaults(arktype(schema));
-	const form = superForm(validated, {
-		validators: arktypeClient(schema),
-		dataType: 'json',
-		invalidateAll,
-		transport: dateTransport,
-		onUpdated({ form }) {
-			const text = form.message?.text;
-			if (text === undefined) return;
-
-			if (form.message?.success) {
-				toast.success(text);
-			} else {
-				toast.error(text);
-			}
-
-			if (form.valid) {
-				onSuccess?.(form);
-			}
-		}
-	});
-	const { form: data, delayed, errors } = form;
-</script>
-
-<form class={className} action="{_action}?/{actionName}" method="POST" use:form.enhance>
-	{@render children({ form, data, delayed, errors })}
-</form> -->
 <script lang="ts" generics="T extends Record<string, unknown>, M">
 	import type { FsSuperForm } from 'formsnap';
 	import type { Snippet } from 'svelte';

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/dist/utils/form/index.d.ts

@@ -1,7 +1,7 @@
 import { type } from 'arktype';
 import { type SuperValidated } from 'sveltekit-superforms';
 export * from './virtual-form.js';
-export declare function prepareForm<S extends type.Any<Record<string, unknown>>>(validated: SuperValidated<S['infer']> | S['infer'], schema: S, options?: Partial<{
+export declare function prepareForm<S extends type.Any<Record<string, unknown>>>(schema: S, validated: SuperValidated<S['infer']> | S['infer'], options?: Partial<{
     invalidateAll: boolean;
     resetForm: boolean;
     onSuccess: (form: Readonly<SuperValidated<S['infer'], App.Superforms.Message, S['infer']>>) => void;
@@ -9,7 +9,7 @@ export declare function prepareForm<S extends type.Any<Record<string, unknown>>>
 }>): {
     form: import("sveltekit-superforms").SuperForm<S["infer"], any>;
     data: import("sveltekit-superforms/client").SuperFormData<S["infer"]>;
-    delayed: import("svelte/store").Readable<boolean>;
+    isProcessing: import("svelte/store").Readable<boolean>;
     errors: import("sveltekit-superforms/client").SuperFormErrors<S["infer"]>;
 };
 export declare function prepareEmptyForm<S extends type.Any<Record<string, unknown>>>(schema: S, options?: Partial<{
@@ -20,6 +20,6 @@ export declare function prepareEmptyForm<S extends type.Any<Record<string, unkno
 }>): {
     form: import("sveltekit-superforms").SuperForm<S["infer"], any>;
     data: import("sveltekit-superforms/client").SuperFormData<S["infer"]>;
-    delayed: import("svelte/store").Readable<boolean>;
+    isProcessing: import("svelte/store").Readable<boolean>;
     errors: import("sveltekit-superforms/client").SuperFormErrors<S["infer"]>;
 };

package/dist/utils/form/index.js

@@ -4,7 +4,7 @@ import { defaults, superForm } from 'sveltekit-superforms';
 import { arktype, arktypeClient } from 'sveltekit-superforms/adapters';
 import { dateTransport } from '../datetime/index.js';
 export * from './virtual-form.js';
-export function prepareForm(validated, schema, options) {
+export function prepareForm(schema, validated, options) {
     const form = superForm(validated, {
         validators: arktypeClient(schema),
         dataType: 'json',
@@ -31,9 +31,9 @@ export function prepareForm(validated, schema, options) {
             toast.error(`${status} - ${message}`);
         }
     });
-    const delayed = form.delayed;
+    const isProcessing = form.delayed;
     const errors = form.errors;
-    return { form, data: form.form, delayed, errors };
+    return { form, data: form.form, isProcessing, errors };
 }
 export function prepareEmptyForm(schema, options) {
     const form = superForm(defaults(arktype(schema)), {
@@ -62,7 +62,7 @@ export function prepareEmptyForm(schema, options) {
             toast.error(`${status} - ${message}`);
         }
     });
-    const delayed = form.delayed;
+    const isProcessing = form.delayed;
     const errors = form.errors;
-    return { form, data: form.form, delayed, errors };
+    return { form, data: form.form, isProcessing, errors };
 }

package/dist/utils/form/virtual-form.d.ts

@@ -10,5 +10,5 @@ export declare class VirtualForm<S extends type.Any<Record<string, unknown>>> {
         onError?: (message: App.Superforms.Message) => void;
     });
     submit(data: S['infer']): Promise<void>;
-    get isLoading(): boolean;
+    get isProcessing(): boolean;
 }

package/dist/utils/form/virtual-form.js

@@ -5,7 +5,7 @@ import { parse, stringify } from 'devalue';
 import { dateTransport } from '../datetime/index.js';
 export class VirtualForm {
     // state storage
-    #isLoading = false;
+    #isProcessing = false;
     #url = '';
     #schema;
     #transport;
@@ -70,7 +70,7 @@ export class VirtualForm {
         return result;
     }
     async submit(data) {
-        this.#isLoading = true;
+        this.#isProcessing = true;
         this.#update();
         // Validate data against schema
         const validated = this.#schema(data);
@@ -99,7 +99,7 @@ export class VirtualForm {
             if (!res.ok || result.status === 400) {
                 console.error('Request failed:', result);
                 this.#onError?.(result);
-                this.#isLoading = false;
+                this.#isProcessing = false;
                 this.#update();
                 return;
             }
@@ -124,11 +124,11 @@ export class VirtualForm {
             console.error(err);
             this.#onError?.({ text: 'Network error', data: err, success: false, showToast: false });
         }
-        this.#isLoading = false;
+        this.#isProcessing = false;
         this.#update();
     }
-    get isLoading() {
+    get isProcessing() {
         this.#subscribe();
-        return this.#isLoading;
+        return this.#isProcessing;
     }
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.3",
+  "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",