@promptbook/cli 0.104.0-3 → 0.104.0-5

package/apps/agents-server/src/app/api/messages/route.ts

@@ -0,0 +1,102 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { $getTableName } from '../../../database/$getTableName';
+import { $provideSupabase } from '../../../database/$provideSupabase';
+import { isUserAdmin } from '../../../utils/isUserAdmin';
+
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 100;
+
+function parsePositiveInt(value: string | null, fallback: number): number {
+    if (!value) return fallback;
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) return fallback;
+    return parsed;
+}
+
+/**
+ * List messages with filters, search and pagination.
+ */
+export async function GET(request: NextRequest) {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const searchParams = request.nextUrl.searchParams;
+
+        const page = parsePositiveInt(searchParams.get('page'), 1);
+        const pageSize = Math.min(MAX_PAGE_SIZE, parsePositiveInt(searchParams.get('pageSize'), DEFAULT_PAGE_SIZE));
+        const search = searchParams.get('search')?.trim() || '';
+        const channel = searchParams.get('channel');
+        const direction = searchParams.get('direction');
+
+        const supabase = $provideSupabase();
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let query = supabase.from(await $getTableName('Message')).select('*', { count: 'exact' });
+
+        if (channel) {
+            query = query.eq('channel', channel);
+        }
+
+        if (direction) {
+            query = query.eq('direction', direction);
+        }
+
+        if (search) {
+            // Search in content, subject (if in metadata?), sender/recipient emails
+            // Note: sender and recipients are JSONB, so ilike might not work directly on them unless cast to text
+            // Content is TEXT.
+            const escaped = search.replace(/%/g, '\\%').replace(/_/g, '\\_');
+            // Assuming simple search on content for now to avoid complexity with JSONB search in generic supabase client
+            query = query.ilike('content', `%${escaped}%`);
+        }
+
+        // Default sort by createdAt desc
+        query = query.order('createdAt', { ascending: false });
+
+        const from = (page - 1) * pageSize;
+        const to = from + pageSize - 1;
+
+        query = query.range(from, to);
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { data: messages, error, count } = (await query) as { data: any[]; error: any; count: number };
+
+        if (error) {
+            console.error('List messages error:', error);
+            return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+        }
+
+        // Fetch attempts for these messages
+        if (messages && messages.length > 0) {
+            const messageIds = messages.map((m) => m.id);
+            const { data: attempts, error: attemptsError } = await supabase
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                .from(await $getTableName('MessageSendAttempt'))
+                .select('*')
+                .in('messageId', messageIds);
+
+            if (attemptsError) {
+                console.error('Fetch message attempts error:', attemptsError);
+                // We don't fail the whole request, just log it.
+            } else {
+                // Attach attempts to messages
+                for (const message of messages) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    (message as any).sendAttempts = attempts?.filter((a: any) => a.messageId === message.id) || [];
+                }
+            }
+        }
+
+        return NextResponse.json({
+            items: messages ?? [],
+            total: count ?? 0,
+            page,
+            pageSize,
+        });
+    } catch (error) {
+        console.error('List messages error:', error);
+        return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+    }
+}

package/apps/agents-server/src/components/Header/Header.tsx

@@ -297,6 +297,10 @@ export function Header(props: HeaderProps) {
                               label: 'Chat history',
                               href: '/admin/chat-history',
                           },
+                          {
+                              label: 'Messages & Emails',
+                              href: '/admin/messages',
+                          },
                           {
                               label: 'Chat feedback',
                               href: '/admin/chat-feedback',

package/apps/agents-server/src/database/$provideSupabaseForBrowser.ts

@@ -1,6 +1,6 @@
-import { AgentsDatabaseSchema } from '@promptbook-local/types';
 import { $isRunningInBrowser } from '@promptbook-local/utils';
 import { createClient, SupabaseClient } from '@supabase/supabase-js';
+import { AgentsServerDatabase } from './schema';
 
 /**
  * Internal cache for `$provideSupabaseForBrowser`
@@ -8,7 +8,7 @@ import { createClient, SupabaseClient } from '@supabase/supabase-js';
  * @private
  * @singleton
  */
-let supabase: SupabaseClient<AgentsDatabaseSchema>;
+let supabase: SupabaseClient<AgentsServerDatabase>;
 
 /**
  * Get supabase client
@@ -27,7 +27,7 @@ export function $provideSupabaseForBrowser(): typeof supabase {
 
     if (!supabase) {
         // Create a single supabase client for interacting with your database
-        supabase = createClient<AgentsDatabaseSchema>(
+        supabase = createClient<AgentsServerDatabase>(
             process.env.NEXT_PUBLIC_SUPABASE_URL!,
             process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
         );

package/apps/agents-server/src/database/$provideSupabaseForServer.ts

@@ -18,7 +18,7 @@ let supabase: SupabaseClient<AgentsServerDatabase>;
  *
  * @returns instance of supabase client
  */
-export function $provideSupabaseForServer(): typeof supabase {
+export function $provideSupabaseForServer(): SupabaseClient<AgentsServerDatabase> {
     if (!$isRunningInNode()) {
         throw new Error(
             'Function `$provideSupabaseForServer` can not be used in browser, use `$provideSupabaseForBrowser` instead.',

package/apps/agents-server/src/database/$provideSupabaseForWorker.ts

@@ -1,6 +1,6 @@
-import { AgentsDatabaseSchema } from '@promptbook-local/types';
 import { $isRunningInWebWorker } from '@promptbook-local/utils';
 import { createClient, SupabaseClient } from '@supabase/supabase-js';
+import { AgentsServerDatabase } from './schema';
 
 /**
  * Internal cache for `$provideSupabaseForWorker`
@@ -8,7 +8,7 @@ import { createClient, SupabaseClient } from '@supabase/supabase-js';
  * @private
  * @singleton
  */
-let supabase: SupabaseClient<AgentsDatabaseSchema>;
+let supabase: SupabaseClient<AgentsServerDatabase>;
 
 /**
  * Get supabase client
@@ -27,7 +27,7 @@ export function $provideSupabaseForWorker(): typeof supabase {
 
     if (!supabase) {
         // Create a single supabase client for interacting with your database
-        supabase = createClient<AgentsDatabaseSchema>(
+        supabase = createClient<AgentsServerDatabase>(
             process.env.NEXT_PUBLIC_SUPABASE_URL!,
             process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
         );

package/apps/agents-server/src/database/migrate.ts

@@ -8,13 +8,34 @@ dotenv.config();
 async function migrate() {
     console.info('🚀 Starting database migration');
 
+    // Parse CLI arguments for --only flag
+    const args = process.argv.slice(2);
+    let onlyPrefixes: string[] | null = null;
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--only' && args[i + 1]) {
+            onlyPrefixes = args[i + 1]
+                .split(',')
+                .map((p) => p.trim())
+                .filter((p) => p !== '');
+            break;
+        } else if (args[i]?.startsWith('--only=')) {
+            onlyPrefixes = args[i]
+                .substring('--only='.length)
+                .split(',')
+                .map((p) => p.trim())
+                .filter((p) => p !== '');
+            break;
+        }
+    }
+
     // 1. Get configuration
     const prefixesEnv = process.env.SUPABASE_MIGRATION_PREFIXES;
     if (!prefixesEnv) {
         console.warn('⚠️ SUPABASE_MIGRATION_PREFIXES is not defined. Skipping migration.');
         return;
     }
-    const prefixes = prefixesEnv
+    let prefixes = prefixesEnv
         .split(',')
         .map((p) => p.trim())
         .filter((p) => p !== '');
@@ -24,6 +45,18 @@ async function migrate() {
         return;
     }
 
+    // Filter prefixes if --only flag is provided
+    if (onlyPrefixes !== null) {
+        const invalidPrefixes = onlyPrefixes.filter((p) => !prefixes.includes(p));
+        if (invalidPrefixes.length > 0) {
+            console.error(`❌ Invalid prefixes specified in --only: ${invalidPrefixes.join(', ')}`);
+            console.error(`   Available prefixes: ${prefixes.join(', ')}`);
+            process.exit(1);
+        }
+        prefixes = onlyPrefixes;
+        console.info(`🎯 Running migrations only for: ${prefixes.join(', ')}`);
+    }
+
     const connectionString = process.env.POSTGRES_URL || process.env.DATABASE_URL;
     if (!connectionString) {
         console.error('❌ POSTGRES_URL or DATABASE_URL is not defined.');

package/apps/agents-server/src/database/migrations/2025-11-0001-initial-schema.sql

@@ -1,6 +1,4 @@
--- Note: This is primary source of truth for the database schema
---       In future we want to be compatible with more then Supabase so we keep SQL as main schema definition
---       To update, search for [💽]
+
 
 
 CREATE TABLE IF NOT EXISTS "prefix_Agent" (

package/apps/agents-server/src/database/migrations/2025-11-0002-metadata-table.sql

@@ -1,6 +1,4 @@
--- Note: This is primary source of truth for the database schema
---       In future we want to be compatible with more then Supabase so we keep SQL as main schema definition
---       To update, search for [💽]
+
 
 
 CREATE TABLE IF NOT EXISTS "prefix_Metadata" (

package/apps/agents-server/src/database/migrations/2025-12-0402-message-table.sql

@@ -0,0 +1,42 @@
+
+-- Table: Message
+CREATE TABLE IF NOT EXISTS "prefix_Message" (
+    "id" BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+    "channel" TEXT NOT NULL,
+    "direction" TEXT NOT NULL,
+    "sender" JSONB NOT NULL,
+    "recipients" JSONB,
+    "content" TEXT NOT NULL,
+    "threadId" TEXT,
+    "metadata" JSONB
+);
+
+COMMENT ON TABLE "prefix_Message" IS 'A generic message structure for various communication channels';
+COMMENT ON COLUMN "prefix_Message"."channel" IS 'The communication channel of the message (e.g. EMAIL, PROMPTBOOK_CHAT)';
+COMMENT ON COLUMN "prefix_Message"."direction" IS 'Is the message send from the Promptbook or to the Promptbook';
+COMMENT ON COLUMN "prefix_Message"."sender" IS 'Who sent the message';
+COMMENT ON COLUMN "prefix_Message"."recipients" IS 'Who are the recipients of the message';
+COMMENT ON COLUMN "prefix_Message"."content" IS 'The content of the message as markdown';
+COMMENT ON COLUMN "prefix_Message"."threadId" IS 'The thread identifier the message belongs to';
+
+
+-- Table: MessageSendAttempt
+CREATE TABLE IF NOT EXISTS "prefix_MessageSendAttempt" (
+    "id" BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+    
+    "messageId" BIGINT NOT NULL REFERENCES "prefix_Message"("id") ON DELETE CASCADE,
+    "providerName" TEXT NOT NULL,
+    "isSuccessful" BOOLEAN NOT NULL,
+    "raw" JSONB
+);
+
+COMMENT ON TABLE "prefix_MessageSendAttempt" IS 'Stores each attempt to send the message';
+COMMENT ON COLUMN "prefix_MessageSendAttempt"."messageId" IS 'The message that was attempted to be sent';
+COMMENT ON COLUMN "prefix_MessageSendAttempt"."providerName" IS 'The name of the provider used for sending';
+COMMENT ON COLUMN "prefix_MessageSendAttempt"."isSuccessful" IS 'Whether the attempt was successful';
+COMMENT ON COLUMN "prefix_MessageSendAttempt"."raw" IS 'Raw response or error from the provider';
+
+ALTER TABLE "prefix_Message" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "prefix_MessageSendAttempt" ENABLE ROW LEVEL SECURITY;

package/apps/agents-server/src/database/schema.ts

@@ -3,7 +3,7 @@
  * Source of truth: `schema.sql` *(do not edit table structure here manually)*
  *
  * [💽] Prompt:
- * Re-generate supabase typescript schema from the `./schema.sql`
+ * Re-generate supabase typescript schema from `./migrations/*.sql`
  */
 
 // Json helper (Supabase style)
@@ -120,7 +120,14 @@ export type AgentsServerDatabase = {
                     agentSource?: string;
                     promptbookEngineVersion?: string;
                 };
-                Relationships: [];
+                Relationships: [
+                    {
+                        foreignKeyName: 'AgentHistory_agentName_fkey';
+                        columns: ['agentName'];
+                        referencedRelation: 'Agent';
+                        referencedColumns: ['agentName'];
+                    },
+                ];
             };
             ChatHistory: {
                 Row: {
@@ -174,7 +181,14 @@ export type AgentsServerDatabase = {
                     source?: 'AGENT_PAGE_CHAT' | 'OPENAI_API_COMPATIBILITY' | null;
                     apiKey?: string | null;
                 };
-                Relationships: [];
+                Relationships: [
+                    {
+                        foreignKeyName: 'ChatHistory_agentName_fkey';
+                        columns: ['agentName'];
+                        referencedRelation: 'Agent';
+                        referencedColumns: ['agentName'];
+                    },
+                ];
             };
             ChatFeedback: {
                 Row: {
@@ -228,7 +242,14 @@ export type AgentsServerDatabase = {
                     language?: string | null;
                     platform?: string | null;
                 };
-                Relationships: [];
+                Relationships: [
+                    {
+                        foreignKeyName: 'ChatFeedback_agentName_fkey';
+                        columns: ['agentName'];
+                        referencedRelation: 'Agent';
+                        referencedColumns: ['agentName'];
+                    },
+                ];
             };
             User: {
                 Row: {
@@ -408,6 +429,76 @@ export type AgentsServerDatabase = {
                     },
                 ];
             };
+            Message: {
+                Row: {
+                    id: number;
+                    createdAt: string;
+                    channel: string;
+                    direction: string;
+                    sender: Json;
+                    recipients: Json | null;
+                    content: string;
+                    threadId: string | null;
+                    metadata: Json | null;
+                };
+                Insert: {
+                    id?: number;
+                    createdAt?: string;
+                    channel: string;
+                    direction: string;
+                    sender: Json;
+                    recipients?: Json | null;
+                    content: string;
+                    threadId?: string | null;
+                    metadata?: Json | null;
+                };
+                Update: {
+                    id?: number;
+                    createdAt?: string;
+                    channel?: string;
+                    direction?: string;
+                    sender?: Json;
+                    recipients?: Json | null;
+                    content?: string;
+                    threadId?: string | null;
+                    metadata?: Json | null;
+                };
+                Relationships: [];
+            };
+            MessageSendAttempt: {
+                Row: {
+                    id: number;
+                    createdAt: string;
+                    messageId: number;
+                    providerName: string;
+                    isSuccessful: boolean;
+                    raw: Json | null;
+                };
+                Insert: {
+                    id?: number;
+                    createdAt?: string;
+                    messageId: number;
+                    providerName: string;
+                    isSuccessful: boolean;
+                    raw?: Json | null;
+                };
+                Update: {
+                    id?: number;
+                    createdAt?: string;
+                    messageId?: number;
+                    providerName?: string;
+                    isSuccessful?: boolean;
+                    raw?: Json | null;
+                };
+                Relationships: [
+                    {
+                        foreignKeyName: 'MessageSendAttempt_messageId_fkey';
+                        columns: ['messageId'];
+                        referencedRelation: 'Message';
+                        referencedColumns: ['id'];
+                    },
+                ];
+            };
         };
         Views: Record<string, never>;
         Functions: Record<string, never>;

package/apps/agents-server/src/message-providers/email/_common/Email.ts

@@ -0,0 +1,73 @@
+import type { Message, string_email, string_person_fullname } from '@promptbook-local/types';
+
+/**
+ * Single email which was received by the application
+ */
+export type InboundEmail = Email & { direction: 'INBOUND' };
+
+/**
+ * Single email which was sended from the application
+ */
+export type OutboundEmail = Email & { direction: 'OUTBOUND' };
+
+/**
+ * Single email
+ */
+type Email = Message<string_email> & {
+    /**
+     * Channel of the message
+     *
+     * @default 'EMAIL'
+     */
+    readonly channel?: 'EMAIL';
+
+    /**
+     * Carbon copy email addresses
+     *
+     * Note: Not working with BCC (Blind Carbon Copy) because we want to have all emails in the same thread
+     *       and for hidden emails we can just call $sendEmail multiple times
+     */
+    readonly cc: Array<EmailAddress>;
+
+    /**
+     * Email subject
+     */
+    readonly subject: string;
+
+    /**
+     * Email attachments
+     */
+    readonly attachments: Array<File>;
+};
+
+export type EmailAddress = {
+    /**
+     * Everything outside of `<>` in email address
+     *
+     * @example "Pavol Hejný <pavol@hejny.cz>" -> "Pavol Hejný"
+     * @example "\"Pavol Hejný\" <pavol@hejny.cz>" -> "Pavol Hejný"
+     */
+    fullName: string_person_fullname | string | null;
+
+    /**
+     * Everything after `+` in email address
+     *
+     * @example "pavol+spam@webgpt.cz" -> ["spam"]
+     * @example "pavol+spam+debug@webgpt.cz" -> ["spam","debug"]
+     */
+    plus: Array<string>;
+
+    /**
+     * Pure email address
+     *
+     * @example "pavol@webgpt.cz"
+     */
+    baseEmail: string_email;
+
+    /**
+     * Full email address without the name but with +
+     *
+     * @example "pavol+test@webgpt.cz"
+     */
+    fullEmail: string_email;
+};

package/apps/agents-server/src/message-providers/email/_common/utils/TODO.txt

@@ -0,0 +1 @@
+TODO: [🧠][🏰] Maybe move all of theese functions into `@promptbook/utils`

package/apps/agents-server/src/message-providers/email/_common/utils/parseEmailAddress.test.ts.todo

@@ -0,0 +1,108 @@
+import { describe, expect, it } from '@jest/globals';
+import { parseEmailAddress } from './parseEmailAddress';
+
+describe('how parseEmailAddress works', () => {
+    it('should work with simple email', () => {
+        expect(parseEmailAddress('pavol@webgpt.cz')).toEqual({
+            fullName: null,
+            baseEmail: 'pavol@webgpt.cz',
+            fullEmail: 'pavol@webgpt.cz',
+            plus: [],
+        });
+        expect(parseEmailAddress('jirka@webgpt.cz')).toEqual({
+            fullName: null,
+            baseEmail: 'jirka@webgpt.cz',
+            fullEmail: 'jirka@webgpt.cz',
+            plus: [],
+        });
+        expect(parseEmailAddress('tomas@webgpt.cz')).toEqual({
+            fullName: null,
+            baseEmail: 'tomas@webgpt.cz',
+            fullEmail: 'tomas@webgpt.cz',
+            plus: [],
+        });
+    });
+
+    it('should work with fullname', () => {
+        expect(parseEmailAddress('Pavol Hejný <pavol@webgpt.cz>')).toEqual({
+            fullName: 'Pavol Hejný',
+            baseEmail: 'pavol@webgpt.cz',
+            fullEmail: 'pavol@webgpt.cz',
+            plus: [],
+        });
+        expect(parseEmailAddress('Jirka <jirka@webgpt.cz>')).toEqual({
+            fullName: 'Jirka',
+            baseEmail: 'jirka@webgpt.cz',
+            fullEmail: 'jirka@webgpt.cz',
+            plus: [],
+        });
+        expect(parseEmailAddress('"Tomáš Studeník" <tomas@webgpt.cz>')).toEqual({
+            fullName: 'Tomáš Studeník',
+            baseEmail: 'tomas@webgpt.cz',
+            fullEmail: 'tomas@webgpt.cz',
+            plus: [],
+        });
+    });
+
+    it('should work with plus', () => {
+        expect(parseEmailAddress('pavol+test@webgpt.cz')).toEqual({
+            fullName: null,
+            baseEmail: 'pavol@webgpt.cz',
+            fullEmail: 'pavol+test@webgpt.cz',
+            plus: ['test'],
+        });
+        expect(parseEmailAddress('jirka+test@webgpt.cz')).toEqual({
+            fullName: null,
+            baseEmail: 'jirka@webgpt.cz',
+            fullEmail: 'jirka+test@webgpt.cz',
+            plus: ['test'],
+        });
+        expect(parseEmailAddress('tomas+test+ainautes@webgpt.cz')).toEqual({
+            fullName: null,
+            baseEmail: 'tomas@webgpt.cz',
+            fullEmail: 'tomas+test+ainautes@webgpt.cz',
+            plus: ['test', 'ainautes'],
+        });
+    });
+
+    it('should work with both fullname and plus', () => {
+        expect(parseEmailAddress('Pavol Hejný <pavol+foo@webgpt.cz>')).toEqual({
+            fullName: 'Pavol Hejný',
+            baseEmail: 'pavol@webgpt.cz',
+            fullEmail: 'pavol+foo@webgpt.cz',
+            plus: ['foo'],
+        });
+        expect(parseEmailAddress('Jirka <jirka+test@webgpt.cz>')).toEqual({
+            fullName: 'Jirka',
+            baseEmail: 'jirka@webgpt.cz',
+            fullEmail: 'jirka+test@webgpt.cz',
+            plus: ['test'],
+        });
+        expect(parseEmailAddress('"Tomáš Studeník" <tomas+test+ainautes@webgpt.cz>')).toEqual({
+            fullName: 'Tomáš Studeník',
+            baseEmail: 'tomas@webgpt.cz',
+            fullEmail: 'tomas+test+ainautes@webgpt.cz',
+            plus: ['test', 'ainautes'],
+        });
+    });
+
+    it('throws on multiple adresses', () => {
+        expect(() => parseEmailAddress('Pavol <pavol@webgpt.cz>, Jirka <jirka@webgpt.cz>')).toThrowError(
+            /Seems like you are trying to parse multiple email addresses/,
+        );
+    });
+
+    it('throws on invalid email adresses', () => {
+        expect(() => parseEmailAddress('')).toThrowError(/Invalid email address/);
+        expect(() => parseEmailAddress('Pavol Hejný')).toThrowError(/Invalid email address/);
+        expect(() => parseEmailAddress('Pavol Hejný <>')).toThrowError(/Invalid email address/);
+        expect(() => parseEmailAddress('Pavol Hejný <@webgpt.cz>')).toThrowError(/Invalid email address/);
+        expect(() => parseEmailAddress('Pavol Hejný <webgpt.cz>')).toThrowError(/Invalid email address/);
+        expect(() => parseEmailAddress('Pavol Hejný <pavol@>')).toThrowError(/Invalid email address/);
+        expect(() => parseEmailAddress('Pavol Hejný <a@b>')).toThrowError(/Invalid email address/);
+    });
+});
+
+/**
+ * TODO: [🐫] This test fails because of aliased imports `import type { string_emails } from '@promptbook-local/types';`, fix it
+ */

package/apps/agents-server/src/message-providers/email/_common/utils/parseEmailAddress.ts

@@ -0,0 +1,62 @@
+import type { string_email } from '@promptbook-local/types';
+import { isValidEmail, spaceTrim } from '@promptbook-local/utils';
+import { EmailAddress } from '../Email';
+
+/**
+ * Parses the email address into its components
+ */
+export function parseEmailAddress(value: string_email): EmailAddress {
+    if (value.includes(',')) {
+        throw new Error('Seems like you are trying to parse multiple email addresses, use parseEmailAddresses instead');
+    }
+
+    let fullName = value.match(/^(?:"?([^"]+)"?|[^<]+)\s*</)?.[1] ?? null;
+
+    if (fullName !== null) {
+        fullName = fullName.trim();
+    }
+
+    const fullEmail = value.match(/<([^>]+)>/)?.[1] ?? value;
+    const plus: Array<string> = [];
+
+    if (!isValidEmail(fullEmail)) {
+        throw new Error(
+            spaceTrim(
+                (block) => `
+                    Invalid email address "${fullEmail}"
+
+                    Parsed:
+                    ${block(JSON.stringify({ fullName, fullEmail, plus }, null, 4))}
+                
+                `,
+            ),
+        );
+    }
+
+    if (fullEmail.includes('+')) {
+        const [user, domain] = fullEmail.split('@');
+
+        if (!user || !domain) {
+            throw new Error('Can not parse email address');
+            //               <- TODO: ShouldNeverHappenError
+        }
+
+        const userParts = user.split('+');
+        userParts.shift();
+
+        plus.push(...userParts);
+    }
+
+    let baseEmail = fullEmail;
+
+    for (const plusItem of plus) {
+        baseEmail = baseEmail.replace(`+${plusItem}`, '');
+    }
+
+    return {
+        fullName,
+        baseEmail,
+        fullEmail,
+        plus,
+    };
+}