@promptbook/cli 0.114.0-10 → 0.114.0-12

package/apps/agents-server/src/app/admin/messages/MessagesClient.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import Link from 'next/link';
 import { useEffect, useMemo, useState } from 'react';
 import { useServerLanguage } from '../../../components/ServerLanguage/ServerLanguageProvider';
 import { Card } from '../../../components/Homepage/Card';
@@ -175,7 +176,13 @@ export function MessagesClient() {
                         Inspect all inbound and outbound messages and their statuses.
                     </p>
                 </div>
-                <div className="flex items-end gap-4 text-sm text-gray-500 md:text-right">
+                <div className="flex flex-wrap items-end gap-4 text-sm text-gray-500 md:text-right">
+                    <Link
+                        href="/admin/messages/send-email"
+                        className="rounded-md border border-blue-600 px-3 py-2 text-sm font-medium text-blue-700 hover:bg-blue-50"
+                    >
+                        Send test email
+                    </Link>
                     <div>
                         <div className="text-xl font-semibold text-gray-900">{total.toLocaleString()}</div>
                         <div className="text-xs uppercase tracking-wide text-gray-400">Total messages</div>

package/apps/agents-server/src/app/admin/messages/send-email/SendEmailClient.tsx

@@ -1,17 +1,131 @@
 'use client';
 
-import { useState } from 'react';
+import { type FormEvent, useState } from 'react';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
 import { sendEmailAction } from './actions';
 
 /**
- * Handles send email client.
+ * Existing agent address offered as a one-click form prefill.
  */
-export function SendEmailClient() {
+export type EmailTestingAgentOption = {
+    readonly id: string;
+    readonly label: string;
+    readonly address: string;
+};
+
+/**
+ * Props accepted by the email testing client.
+ */
+type SendEmailClientProps = {
+    readonly currentServerDomain: string;
+    readonly isGlobalAdmin: boolean;
+    readonly agentEmailOptions: ReadonlyArray<EmailTestingAgentOption>;
+};
+
+/**
+ * Props accepted by an address editor with optional agent-address prefills.
+ */
+type EmailTestingAddressInputProps = {
+    readonly label: string;
+    readonly name: 'from' | 'to';
+    readonly value: string;
+    readonly placeholder: string;
+    readonly helperText: string;
+    readonly agentEmailOptions: ReadonlyArray<EmailTestingAgentOption>;
+    readonly isDisabled: boolean;
+    readonly onValueChange: (value: string) => void;
+};
+
+/**
+ * Renders one arbitrary email-address input and lets administrators pre-fill it from an existing agent.
+ */
+function EmailTestingAddressInput({
+    label,
+    name,
+    value,
+    placeholder,
+    helperText,
+    agentEmailOptions,
+    isDisabled,
+    onValueChange,
+}: EmailTestingAddressInputProps) {
+    const helperTextId = `${name}-helper-text`;
+
+    return (
+        <div>
+            <div className="flex flex-wrap items-center justify-between gap-2">
+                <label htmlFor={name} className="block text-sm font-medium text-gray-700">
+                    {label}
+                </label>
+                {agentEmailOptions.length > 0 ? (
+                    <select
+                        aria-label={`Pre-fill ${label.toLowerCase()} with an existing agent address`}
+                        value=""
+                        onChange={(event) => {
+                            if (event.target.value) {
+                                onValueChange(event.target.value);
+                            }
+                        }}
+                        disabled={isDisabled}
+                        className="rounded-md border border-gray-300 bg-white px-2 py-1 text-xs text-gray-700"
+                    >
+                        <option value="">Pre-fill from an agent</option>
+                        {agentEmailOptions.map((agent) => (
+                            <option key={agent.id} value={agent.address}>
+                                {agent.label} — {agent.address}
+                            </option>
+                        ))}
+                    </select>
+                ) : null}
+            </div>
+            <input
+                id={name}
+                name={name}
+                type="text"
+                value={value}
+                onChange={(event) => onValueChange(event.target.value)}
+                placeholder={placeholder}
+                aria-describedby={helperTextId}
+                required
+                disabled={isDisabled}
+                className="mt-1 block w-full rounded-md border border-gray-300 p-2 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 disabled:bg-gray-100"
+            />
+            <p id={helperTextId} className="mt-1 text-xs text-gray-500">
+                {helperText}
+            </p>
+        </div>
+    );
+}
+
+/**
+ * Explains the domain scope available to the current administrator.
+ */
+function getEmailTestingScopeMessage(currentServerDomain: string, isGlobalAdmin: boolean): string {
+    if (isGlobalAdmin) {
+        return 'As the superadmin, you can use a sender address from any domain.';
+    }
+
+    return `You can use any recipient address, but the sender must use ${currentServerDomain}.`;
+}
+
+/**
+ * Renders and submits the administration email testing form.
+ */
+export function SendEmailClient({
+    currentServerDomain,
+    isGlobalAdmin,
+    agentEmailOptions,
+}: SendEmailClientProps) {
     const [status, setStatus] = useState<'IDLE' | 'LOADING' | 'SUCCESS' | 'ERROR'>('IDLE');
     const [errorMessage, setErrorMessage] = useState<string | null>(null);
+    const [from, setFrom] = useState('');
+    const [to, setTo] = useState('');
+    const isLoading = status === 'LOADING';
 
-    const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
+    /**
+     * Sends the currently composed test email and displays the server-side outcome.
+     */
+    const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
         event.preventDefault();
         setStatus('LOADING');
         setErrorMessage(null);
@@ -31,77 +145,93 @@ export function SendEmailClient() {
 
     return (
         <div className="container mx-auto p-4">
-            <h1 className="text-2xl font-bold mb-4">Send Email (Test)</h1>
-
-            {status === 'SUCCESS' && (
-                <div className="bg-green-100 border border-green-400 text-green-700 px-4 py-3 rounded mb-4">
-                    Email sent successfully!
+            <div className="mx-auto mt-20 max-w-2xl space-y-6">
+                <div>
+                    <h1 className="text-3xl font-light text-gray-900">Email testing</h1>
+                    <p className="mt-1 text-sm text-gray-500">
+                        Send a manually composed email through this server&apos;s email service.
+                    </p>
+                    <p className="mt-2 rounded-md bg-blue-50 px-3 py-2 text-sm text-blue-950">
+                        {getEmailTestingScopeMessage(currentServerDomain, isGlobalAdmin)}
+                    </p>
                 </div>
-            )}
 
-            {status === 'ERROR' && (
-                <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded mb-4">
-                    Error: {errorMessage}
-                </div>
-            )}
+                {status === 'SUCCESS' && (
+                    <div className="rounded border border-green-400 bg-green-100 px-4 py-3 text-green-700">
+                        Email sent successfully!
+                    </div>
+                )}
 
-            <form onSubmit={handleSubmit} className="space-y-4 max-w-lg">
-                <div>
-                    <label className="block text-sm font-medium text-gray-700">From</label>
-                    <input
+                {status === 'ERROR' && (
+                    <div className="rounded border border-red-400 bg-red-100 px-4 py-3 text-red-700">
+                        Error: {errorMessage}
+                    </div>
+                )}
+
+                <form onSubmit={handleSubmit} className="space-y-4 rounded-xl border border-gray-200 bg-white p-5 shadow-sm">
+                    <EmailTestingAddressInput
+                        label="From"
                         name="from"
-                        type="text"
-                        defaultValue="Test Promptbook <test@ptbk.io>"
-                        required
-                        className="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 border p-2"
+                        value={from}
+                        onValueChange={setFrom}
+                        placeholder={`Sender <sender@${currentServerDomain}>`}
+                        helperText="Enter any valid sender address, or pre-fill one of this server's agents."
+                        agentEmailOptions={agentEmailOptions}
+                        isDisabled={isLoading}
                     />
-                </div>
 
-                <div>
-                    <label className="block text-sm font-medium text-gray-700">To</label>
-                    <input
+                    <EmailTestingAddressInput
+                        label="To"
                         name="to"
-                        type="text"
+                        value={to}
+                        onValueChange={setTo}
                         placeholder="recipient@example.com"
-                        defaultValue="Pavol Hejný <pavol@ptbk.io>"
-                        required
-                        className="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 border p-2"
+                        helperText="Separate multiple addresses with commas."
+                        agentEmailOptions={agentEmailOptions}
+                        isDisabled={isLoading}
                     />
-                    <p className="text-xs text-gray-500 mt-1">Separate multiple addresses with commas</p>
-                </div>
 
-                <div>
-                    <label className="block text-sm font-medium text-gray-700">Subject</label>
-                    <input
-                        name="subject"
-                        type="text"
-                        placeholder="Test Email"
-                        defaultValue="Test Email"
-                        required
-                        className="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 border p-2"
-                    />
-                </div>
+                    <div>
+                        <label htmlFor="subject" className="block text-sm font-medium text-gray-700">
+                            Subject
+                        </label>
+                        <input
+                            id="subject"
+                            name="subject"
+                            type="text"
+                            placeholder="Test email"
+                            defaultValue="Test email"
+                            required
+                            disabled={isLoading}
+                            className="mt-1 block w-full rounded-md border border-gray-300 p-2 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 disabled:bg-gray-100"
+                        />
+                    </div>
 
-                <div>
-                    <label className="block text-sm font-medium text-gray-700">Body</label>
-                    <textarea
-                        name="body"
-                        rows={6}
-                        placeholder="Hello, this is a test email."
-                        defaultValue="Hello, this is a test email."
-                        required
-                        className="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 border p-2"
-                    />
-                </div>
+                    <div>
+                        <label htmlFor="body" className="block text-sm font-medium text-gray-700">
+                            Body
+                        </label>
+                        <textarea
+                            id="body"
+                            name="body"
+                            rows={6}
+                            placeholder="Hello, this is a test email."
+                            defaultValue="Hello, this is a test email."
+                            required
+                            disabled={isLoading}
+                            className="mt-1 block w-full rounded-md border border-gray-300 p-2 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 disabled:bg-gray-100"
+                        />
+                    </div>
 
-                <button
-                    type="submit"
-                    disabled={status === 'LOADING'}
-                    className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded disabled:opacity-50"
-                >
-                    {status === 'LOADING' ? 'Sending...' : 'Send Email'}
-                </button>
-            </form>
+                    <button
+                        type="submit"
+                        disabled={isLoading}
+                        className="rounded bg-blue-500 px-4 py-2 font-bold text-white hover:bg-blue-700 disabled:opacity-50"
+                    >
+                        {isLoading ? 'Sending...' : 'Send email'}
+                    </button>
+                </form>
+            </div>
         </div>
     );
 }

package/apps/agents-server/src/app/admin/messages/send-email/actions.ts

@@ -1,38 +1,35 @@
 'use server';
 
-import type { string_email, string_emails, string_html } from '@promptbook-local/types';
-import { parseEmailAddress } from '../../../../message-providers/email/_common/utils/parseEmailAddress';
-import { parseEmailAddresses } from '../../../../message-providers/email/_common/utils/parseEmailAddresses';
-import { stringifyEmailAddress } from '../../../../message-providers/email/_common/utils/stringifyEmailAddress';
-import { sendMessage } from '../../../../utils/messages/sendMessage';
+import { NotAllowed } from '../../../../../../../src/errors/NotAllowed';
+import { spaceTrim } from '../../../../../../../src/utils/organization/spaceTrim';
+import { sendEmailThroughStalwart } from '../../../../utils/email/sendEmailThroughStalwart';
+import {
+    assertEmailTestingSenderDomainAllowed,
+    createEmailTestingOutboundEmail,
+    readEmailTestingFormValues,
+} from './emailTesting';
+import { getEmailTestingAccessContext } from './emailTestingAccess';
 
 /**
- * Handles send email action.
+ * Sends an administrator-composed test email through the bundled Stalwart email service.
  */
-export async function sendEmailAction(formData: FormData) {
-    const from = formData.get('from') as string;
-    const to = formData.get('to') as string;
-    const subject = formData.get('subject') as string;
-    const body = formData.get('body') as string;
+export async function sendEmailAction(formData: FormData): Promise<void> {
+    const accessContext = await getEmailTestingAccessContext();
 
-    if (!from || !to || !subject || !body) {
-        throw new Error('All fields are required');
+    if (!accessContext) {
+        throw new NotAllowed(
+            spaceTrim(`
+                You are not allowed to send test emails.
+            `),
+        );
     }
 
-    const sender = stringifyEmailAddress(parseEmailAddress(from as string_email));
-    const recipients = parseEmailAddresses(to as string_emails).map(stringifyEmailAddress);
-
-    await sendMessage({
-        channel: 'EMAIL',
-        direction: 'OUTBOUND',
-        sender,
-        recipients,
-        subject,
-        content: body as string_html,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        threadId: crypto.randomUUID() as any,
-        cc: [],
-        attachments: [],
-        metadata: {},
+    const email = createEmailTestingOutboundEmail(readEmailTestingFormValues(formData));
+    assertEmailTestingSenderDomainAllowed({
+        sender: email.sender,
+        currentServerDomain: accessContext.currentServerDomain,
+        isGlobalAdmin: accessContext.isGlobalAdmin,
     });
+
+    await sendEmailThroughStalwart(email);
 }

package/apps/agents-server/src/app/admin/messages/send-email/emailTesting.ts

@@ -0,0 +1,153 @@
+import type { string_email, string_emails, string_markdown } from '@promptbook-local/types';
+import { NotAllowed } from '../../../../../../../src/errors/NotAllowed';
+import { ParseError } from '../../../../../../../src/errors/ParseError';
+import { spaceTrim } from '../../../../../../../src/utils/organization/spaceTrim';
+import type { OutboundEmail } from '../../../../message-providers/email/_common/Email';
+import { parseEmailAddress } from '../../../../message-providers/email/_common/utils/parseEmailAddress';
+import { parseEmailAddresses } from '../../../../message-providers/email/_common/utils/parseEmailAddresses';
+import { stringifyEmailAddress } from '../../../../message-providers/email/_common/utils/stringifyEmailAddress';
+import { getEmailAddressDomain, normalizeEmailDomain } from '../../../../utils/email/agentEmailAddress';
+
+/**
+ * Raw values submitted through the administration email testing form.
+ */
+export type EmailTestingFormValues = {
+    readonly from: string;
+    readonly to: string;
+    readonly subject: string;
+    readonly body: string;
+};
+
+/**
+ * Reads and validates the required values of the administration email testing form.
+ */
+export function readEmailTestingFormValues(formData: FormData): EmailTestingFormValues {
+    return {
+        from: readRequiredEmailTestingFormText(formData, 'from'),
+        to: readRequiredEmailTestingFormText(formData, 'to'),
+        subject: readRequiredEmailTestingFormText(formData, 'subject'),
+        body: readRequiredEmailTestingFormText(formData, 'body'),
+    };
+}
+
+/**
+ * Creates the normalized outbound email persisted and delivered by the testing tool.
+ */
+export function createEmailTestingOutboundEmail(formValues: EmailTestingFormValues): OutboundEmail {
+    const sender = parseEmailTestingSender(formValues.from);
+    const recipients = parseEmailTestingRecipients(formValues.to);
+
+    return {
+        channel: 'EMAIL',
+        direction: 'OUTBOUND',
+        sender,
+        recipients,
+        subject: formValues.subject,
+        content: formValues.body as string_markdown,
+        threadId: crypto.randomUUID(),
+        cc: [],
+        attachments: [],
+        metadata: {},
+    };
+}
+
+/**
+ * Ensures that a normal administrator sends test mail only from the current server's domain.
+ */
+export function assertEmailTestingSenderDomainAllowed(options: {
+    readonly sender: string_email;
+    readonly currentServerDomain: string;
+    readonly isGlobalAdmin: boolean;
+}): void {
+    if (options.isGlobalAdmin) {
+        return;
+    }
+
+    const senderDomain = getEmailAddressDomain(options.sender);
+    const currentServerDomain = normalizeEmailDomain(options.currentServerDomain);
+
+    if (senderDomain === currentServerDomain) {
+        return;
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            You are only allowed to send test emails from the current server's domain.
+
+            **Current server domain:** \`${currentServerDomain}\`
+            **Sender domain:** \`${senderDomain}\`
+        `),
+    );
+}
+
+/**
+ * Reads one required string value from the submitted email testing form.
+ */
+function readRequiredEmailTestingFormText(formData: FormData, fieldName: string): string {
+    const value = formData.get(fieldName);
+
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new ParseError(
+            spaceTrim(`
+                The \`${fieldName}\` field is required to send a test email.
+            `),
+        );
+    }
+
+    return value;
+}
+
+/**
+ * Parses one sender while converting parser failures into a user-facing branded error.
+ */
+function parseEmailTestingSender(value: string): string_email {
+    try {
+        return stringifyEmailAddress(parseEmailAddress(value.trim() as string_email));
+    } catch (error) {
+        throw new ParseError(
+            spaceTrim(`
+                The \`from\` email address is invalid.
+
+                **Cause:** \`${getEmailTestingErrorMessage(error)}\`
+            `),
+        );
+    }
+}
+
+/**
+ * Parses one or more comma-separated recipients into transport-ready addresses.
+ */
+function parseEmailTestingRecipients(value: string): string_email[] {
+    let recipients: string_email[];
+
+    try {
+        recipients = parseEmailAddresses(value.trim() as string_emails).map(stringifyEmailAddress);
+    } catch (error) {
+        throw new ParseError(
+            spaceTrim(`
+                The \`to\` email address is invalid.
+
+                **Cause:** \`${getEmailTestingErrorMessage(error)}\`
+            `),
+        );
+    }
+
+    if (recipients.length > 0) {
+        return recipients;
+    }
+
+    throw new ParseError(
+        spaceTrim(`
+            The \`to\` email address is invalid.
+
+            **Cause:** \`No recipient email addresses were provided.\`
+        `),
+    );
+}
+
+/**
+ * Gets a safe textual reason from an arbitrary parsing failure.
+ */
+function getEmailTestingErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}

package/apps/agents-server/src/app/admin/messages/send-email/emailTestingAccess.ts

@@ -0,0 +1,30 @@
+import { $provideServer } from '../../../../tools/$provideServer';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
+import { isUserGlobalAdmin } from '../../../../utils/isUserGlobalAdmin';
+import { normalizeEmailDomain } from '../../../../utils/email/agentEmailAddress';
+
+/**
+ * Authorization and server scope available to the administration email testing tool.
+ */
+export type EmailTestingAccessContext = {
+    readonly currentServerDomain: string;
+    readonly isGlobalAdmin: boolean;
+};
+
+/**
+ * Resolves access to the email testing tool for either a current-server admin or the VPS superadmin.
+ */
+export async function getEmailTestingAccessContext(): Promise<EmailTestingAccessContext | null> {
+    const [isAdmin, isGlobalAdmin] = await Promise.all([isUserAdmin(), isUserGlobalAdmin()]);
+
+    if (!isAdmin && !isGlobalAdmin) {
+        return null;
+    }
+
+    const server = await $provideServer();
+
+    return {
+        currentServerDomain: normalizeEmailDomain(server.publicUrl.hostname),
+        isGlobalAdmin,
+    };
+}

package/apps/agents-server/src/app/admin/messages/send-email/page.tsx

@@ -1,16 +1,29 @@
 import { ForbiddenPage } from '../../../../components/ForbiddenPage/ForbiddenPage';
-import { isUserAdmin } from '../../../../utils/isUserAdmin';
+import { listAgentEmailIdentities } from '../../../../utils/email/listAgentEmailIdentities';
 import { SendEmailClient } from './SendEmailClient';
+import { getEmailTestingAccessContext } from './emailTestingAccess';
 
 /**
- * Handles admin send email page.
+ * Renders the current server's email testing tool.
  */
 export default async function AdminSendEmailPage() {
-    const isAdmin = await isUserAdmin();
+    const accessContext = await getEmailTestingAccessContext();
 
-    if (!isAdmin) {
+    if (!accessContext) {
         return <ForbiddenPage />;
     }
 
-    return <SendEmailClient />;
+    const agentEmailOptions = (await listAgentEmailIdentities(accessContext.currentServerDomain)).map((agent) => ({
+        id: agent.permanentId,
+        label: agent.displayName,
+        address: agent.preferredEmail,
+    }));
+
+    return (
+        <SendEmailClient
+            currentServerDomain={accessContext.currentServerDomain}
+            isGlobalAdmin={accessContext.isGlobalAdmin}
+            agentEmailOptions={agentEmailOptions}
+        />
+    );
 }