@xcelsior/support-api 0.1.1

package/packages/functions/services/emailService.ts

@@ -0,0 +1,160 @@
+import { emailTransporter } from '@xcelsior/email';
+import { logger } from '../config';
+
+/**
+ * Check if email is configured - email sending is optional
+ */
+export const isEmailConfigured = (): boolean => {
+    const transport = process.env.EMAIL_TRANSPORT;
+    if (!transport) return false;
+
+    if (transport === 'smtp') {
+        return Boolean(process.env.SMTP_HOST);
+    }
+
+    // For SES transport
+    return true;
+};
+
+export interface AssignmentEmailOptions {
+    to: string;
+    ticketNumber: number;
+    ticketId: string;
+    subject: string;
+    priority?: string | null;
+    requesterName: string;
+    requesterEmail: string;
+}
+
+export const sendAssignmentEmail = async (options: AssignmentEmailOptions): Promise<void> => {
+    if (!isEmailConfigured()) {
+        logger.info('Email not configured, skipping assignment notification');
+        return;
+    }
+
+    const { to, ticketNumber, ticketId, subject, priority, requesterName, requesterEmail } =
+        options;
+
+    const emailSender = process.env.EMAIL_SENDER || 'noreply@xcelsior.au';
+    const appUrl = process.env.APP_URL || '';
+    const ticketUrl = appUrl ? `${appUrl}/support/tickets/${ticketId}` : '';
+
+    try {
+        const transporter = emailTransporter(logger);
+        await transporter.sendMail({
+            to,
+            from: emailSender,
+            subject: `[Ticket #${ticketNumber}] You have been assigned: ${subject}`,
+            text: `You have been assigned to support ticket #${ticketNumber}.\n\nSubject: ${subject}\nPriority: ${priority || 'Not set'}\nRequester: ${requesterName} (${requesterEmail})\n\n${ticketUrl ? `View ticket: ${ticketUrl}` : ''}`,
+            template: `
+                <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
+                    <h2>New Ticket Assignment</h2>
+                    <p>You have been assigned to support ticket <strong>#${ticketNumber}</strong>.</p>
+                    <div style="background-color: #f5f5f5; padding: 20px; border-radius: 8px; margin: 20px 0;">
+                        <p><strong>Subject:</strong> ${subject}</p>
+                        <p><strong>Priority:</strong> ${priority || 'Not set'}</p>
+                        <p><strong>Requester:</strong> ${requesterName} (${requesterEmail})</p>
+                    </div>
+                    ${ticketUrl ? `<p><a href="${ticketUrl}" style="display: inline-block; background-color: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 4px;">View Ticket</a></p>` : ''}
+                </div>
+            `,
+            reference: `ticket-assignment-${ticketId}`,
+            idempotencyKey: `ticket-assignment-${ticketId}-${to}`,
+        });
+
+        logger.info('Assignment notification email sent', {
+            ticketId,
+            ticketNumber,
+            assigneeEmail: to,
+        });
+    } catch (error) {
+        logger.error('Failed to send assignment notification email', {
+            error: error instanceof Error ? error.message : 'Unknown error',
+            ticketId,
+            ticketNumber,
+            assigneeEmail: to,
+        });
+        // Don't throw - email failure shouldn't fail the ticket operation
+    }
+};
+
+export interface ReminderEmailOptions {
+    to: string;
+    ticketNumber: number;
+    ticketId: string;
+    subject: string;
+    priority?: string | null;
+    status: string;
+    requesterName: string;
+    requesterEmail: string;
+    reminderAt: string;
+    createdAt: string;
+}
+
+export const sendReminderEmail = async (options: ReminderEmailOptions): Promise<void> => {
+    if (!isEmailConfigured()) {
+        logger.info('Email not configured, skipping reminder notification');
+        return;
+    }
+
+    const {
+        to,
+        ticketNumber,
+        ticketId,
+        subject,
+        priority,
+        status,
+        requesterName,
+        requesterEmail,
+        reminderAt,
+        createdAt,
+    } = options;
+
+    const emailSender = process.env.EMAIL_SENDER || 'noreply@xcelsior.au';
+    const appUrl = process.env.APP_URL || '';
+    const ticketUrl = appUrl ? `${appUrl}/support/tickets/${ticketId}` : '';
+
+    const createdDate = new Date(createdAt).toLocaleDateString();
+    const reminderDate = new Date(reminderAt).toLocaleDateString();
+
+    try {
+        const transporter = emailTransporter(logger);
+        await transporter.sendMail({
+            to,
+            from: emailSender,
+            subject: `[Reminder] Ticket #${ticketNumber} requires attention: ${subject}`,
+            text: `This is a reminder that ticket #${ticketNumber} has not been resolved and requires your attention.\n\nSubject: ${subject}\nStatus: ${status}\nPriority: ${priority || 'Not set'}\nCreated: ${createdDate}\nDue: ${reminderDate}\nRequester: ${requesterName} (${requesterEmail})\n\n${ticketUrl ? `View ticket: ${ticketUrl}` : ''}`,
+            template: `
+                <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
+                    <h2 style="color: #dc3545;">⏰ Ticket Reminder</h2>
+                    <p>This is a reminder that ticket <strong>#${ticketNumber}</strong> has not been resolved and requires your attention.</p>
+                    <div style="background-color: #fff3cd; padding: 20px; border-radius: 8px; margin: 20px 0; border-left: 4px solid #ffc107;">
+                        <p><strong>Subject:</strong> ${subject}</p>
+                        <p><strong>Status:</strong> ${status}</p>
+                        <p><strong>Priority:</strong> ${priority || 'Not set'}</p>
+                        <p><strong>Created:</strong> ${createdDate}</p>
+                        <p><strong>Due:</strong> ${reminderDate}</p>
+                        <p><strong>Requester:</strong> ${requesterName} (${requesterEmail})</p>
+                    </div>
+                    ${ticketUrl ? `<p><a href="${ticketUrl}" style="display: inline-block; background-color: #dc3545; color: white; padding: 10px 20px; text-decoration: none; border-radius: 4px;">View Ticket</a></p>` : ''}
+                </div>
+            `,
+            reference: `ticket-reminder-${ticketId}`,
+            idempotencyKey: `ticket-reminder-${ticketId}-${reminderAt}`,
+        });
+
+        logger.info('Reminder notification email sent', {
+            ticketId,
+            ticketNumber,
+            assigneeEmail: to,
+        });
+    } catch (error) {
+        logger.error('Failed to send reminder notification email', {
+            error: error instanceof Error ? error.message : 'Unknown error',
+            ticketId,
+            ticketNumber,
+            assigneeEmail: to,
+        });
+        // Don't throw - email failure shouldn't fail the reminder operation
+    }
+};

package/packages/functions/teams/addMember.ts

@@ -0,0 +1,69 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, TEAMS_TABLE } from '../config';
+import { middyfy, NotFoundError, ValidationError } from '@xcelsior/lambda-http';
+import { teamMemberSchema } from '../types';
+import { z } from 'zod';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const addTeamMember = async (event: APIGatewayProxyEventV2) => {
+    let payload;
+    try {
+        payload = teamMemberSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid member payload', error.errors);
+        }
+        throw error;
+    }
+
+    const id = event.pathParameters?.id;
+    if (!id) {
+        throw new ValidationError('Team id is required', []);
+    }
+
+    const team = await DynamoDBService.getItem<any>(
+        {
+            tableName: TEAMS_TABLE,
+            key: id,
+        },
+        logger
+    );
+
+    if (!team) {
+        throw new NotFoundError('Team not found');
+    }
+
+    const members: string[] = Array.isArray(team.members) ? team.members : [];
+    if (!members.includes(payload.userId)) {
+        members.push(payload.userId);
+    }
+
+    const updated = await DynamoDBService.updateItem(
+        {
+            tableName: TEAMS_TABLE,
+            key: { id },
+            updateExpression: 'SET members = :members, updatedAt = :updatedAt',
+            expressionAttributeValues: {
+                ':members': members,
+                ':updatedAt': new Date().toISOString(),
+            },
+        },
+        logger
+    );
+
+    logger.info('Add team member', { teamId: id, userId: payload.userId });
+
+    const safeUpdated = (updated as any) ?? {
+        id,
+        isDefault: false,
+        members,
+    };
+
+    return createResponse({
+        ...safeUpdated,
+        isDefault: safeUpdated.isDefault === true,
+        members: safeUpdated.members ?? members,
+    });
+};
+
+export const handler = middyfy(addTeamMember, middlewareConfig);

package/packages/functions/teams/create.ts

@@ -0,0 +1,46 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, TEAMS_TABLE } from '../config';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import { teamCreateSchema } from '../types';
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const createTeam = async (event: APIGatewayProxyEventV2) => {
+    let payload;
+    try {
+        payload = teamCreateSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid team payload', error.errors);
+        }
+        throw error;
+    }
+
+    const now = new Date().toISOString();
+    const team = {
+        id: randomUUID(),
+        name: payload.name,
+        type: payload.type,
+        isDefault: false,
+        members: [],
+        createdAt: now,
+        updatedAt: now,
+    };
+
+    logger.info('Create team', { teamId: team.id });
+
+    await DynamoDBService.putItem(
+        {
+            tableName: TEAMS_TABLE,
+            item: team,
+        },
+        logger
+    );
+
+    return createResponse({
+        ...team,
+    });
+};
+
+export const handler = middyfy(createTeam, middlewareConfig);

package/packages/functions/teams/list.ts

@@ -0,0 +1,31 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, TEAMS_TABLE } from '../config';
+import { middyfy } from '@xcelsior/lambda-http';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const listTeams = async (_event: APIGatewayProxyEventV2) => {
+    logger.info('List teams');
+
+    const result = await DynamoDBService.scanItems<any>(
+        {
+            tableName: TEAMS_TABLE,
+            filterExpression: 'attribute_not_exists(archivedAt)',
+        },
+        logger
+    );
+
+    const items = result.items.map((item) => ({
+        ...item,
+        isDefault: item.isDefault === true,
+        members: item.members ?? [],
+    }));
+
+    return createResponse({
+        items,
+        nextToken: result.nextToken
+            ? Buffer.from(JSON.stringify(result.nextToken)).toString('base64')
+            : undefined,
+    });
+};
+
+export const handler = middyfy(listTeams, middlewareConfig);

package/packages/functions/teams/removeMember.ts

@@ -0,0 +1,56 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, TEAMS_TABLE } from '../config';
+import { middyfy, NotFoundError, ValidationError } from '@xcelsior/lambda-http';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const removeTeamMember = async (event: APIGatewayProxyEventV2) => {
+    const id = event.pathParameters?.id;
+    const userId = event.pathParameters?.userId;
+    if (!id || !userId) {
+        throw new ValidationError('Team id and user id are required', []);
+    }
+
+    const team = await DynamoDBService.getItem<any>(
+        {
+            tableName: TEAMS_TABLE,
+            key: id,
+        },
+        logger
+    );
+
+    if (!team) {
+        throw new NotFoundError('Team not found');
+    }
+
+    const members: string[] = Array.isArray(team.members) ? team.members : [];
+    const updatedMembers = members.filter((m) => m !== userId);
+
+    const updated = await DynamoDBService.updateItem(
+        {
+            tableName: TEAMS_TABLE,
+            key: { id },
+            updateExpression: 'SET members = :members, updatedAt = :updatedAt',
+            expressionAttributeValues: {
+                ':members': updatedMembers,
+                ':updatedAt': new Date().toISOString(),
+            },
+        },
+        logger
+    );
+
+    logger.info('Remove team member', { teamId: id, userId });
+
+    const safeUpdated = (updated as any) ?? {
+        id,
+        isDefault: false,
+        members: updatedMembers,
+    };
+
+    return createResponse({
+        ...safeUpdated,
+        isDefault: safeUpdated.isDefault === true,
+        members: safeUpdated.members ?? updatedMembers,
+    });
+};
+
+export const handler = middyfy(removeTeamMember, middlewareConfig);

package/packages/functions/tickets/create.ts

@@ -0,0 +1,179 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import {
+    CATEGORIES_TABLE,
+    createResponse,
+    logger,
+    middlewareConfig,
+    REMINDER_QUEUE,
+    SUPPORT_CONFIG_TABLE,
+    TEAMS_TABLE,
+    TICKET_EVENTS_TABLE,
+    TICKETS_TABLE,
+} from '../config';
+import { middyfy, NotFoundError, ValidationError } from '@xcelsior/lambda-http';
+import { ticketCreateSchema } from '../types';
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+import { SqsService } from '@xcelsior/aws/src/sqs';
+
+type SlaConfig = { low?: number; medium?: number; high?: number; critical?: number };
+
+const defaultSla: Required<SlaConfig> = { low: 7, medium: 5, high: 3, critical: 1 };
+
+const computeReminderAt = (priority?: string, sla?: SlaConfig) => {
+    const days =
+        ((sla?.[priority as keyof SlaConfig] ?? defaultSla[priority as keyof typeof defaultSla]) as
+            | number
+            | undefined) || 5;
+    const date = new Date();
+    date.setDate(date.getDate() + days);
+    return date.toISOString();
+};
+
+const createTicket = async (event: APIGatewayProxyEventV2) => {
+    let payload;
+    try {
+        payload = ticketCreateSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid ticket payload', error.errors);
+        }
+        throw error;
+    }
+
+    const now = new Date().toISOString();
+
+    const config = await DynamoDBService.getItem<{
+        id: string;
+        notification?: { emailOnAssignment?: boolean };
+        sla?: SlaConfig;
+    }>(
+        {
+            tableName: SUPPORT_CONFIG_TABLE,
+            key: 'support-config',
+        },
+        logger
+    );
+
+    const sla: SlaConfig = config?.sla ?? defaultSla;
+
+    const category = await DynamoDBService.getItem<any>(
+        {
+            tableName: CATEGORIES_TABLE,
+            key: payload.categoryId,
+        },
+        logger
+    );
+
+    if (!category || category.archivedAt) {
+        throw new NotFoundError('Category not found');
+    }
+
+    const team = await DynamoDBService.getItem<any>(
+        {
+            tableName: TEAMS_TABLE,
+            key: payload.teamId,
+        },
+        logger
+    );
+
+    if (!team) {
+        throw new NotFoundError('Team not found');
+    }
+
+    const members: string[] = Array.isArray(team.members) ? team.members : [];
+    if (payload.assigneeUserId && !members.includes(payload.assigneeUserId)) {
+        throw new ValidationError('Assignee must belong to the team', []);
+    }
+
+    const attachments = payload.attachments ?? [];
+    const reminderAt =
+        payload.priority && payload.priority !== undefined
+            ? computeReminderAt(payload.priority, sla)
+            : undefined;
+
+    // Generate sequential ticket number using atomic counter
+    const ticketNumber = await DynamoDBService.incrementCounter(
+        {
+            tableName: SUPPORT_CONFIG_TABLE,
+            key: 'ticket-counter',
+            attributeName: 'counter',
+        },
+        logger
+    );
+
+    const ticket = {
+        id: randomUUID(),
+        ticketNumber,
+        categoryId: payload.categoryId,
+        teamId: payload.teamId,
+        subject: payload.subject,
+        description: payload.description ?? null,
+        status: 'New',
+        priority: payload.priority ?? null,
+        assigneeUserId: payload.assigneeUserId ?? null,
+        assigneeEmail: payload.assigneeEmail ?? null,
+        requesterName: payload.requesterName,
+        requesterEmail: payload.requesterEmail,
+        attachments,
+        reminderAt,
+        createdAt: now,
+        updatedAt: now,
+    };
+
+    logger.info('Create ticket', { ticketId: ticket.id });
+
+    await DynamoDBService.putItem(
+        {
+            tableName: TICKETS_TABLE,
+            item: ticket,
+        },
+        logger
+    );
+
+    await DynamoDBService.putItem(
+        {
+            tableName: TICKET_EVENTS_TABLE,
+            item: {
+                id: randomUUID(),
+                ticketId: ticket.id,
+                type: 'created',
+                payload: {
+                    requester: ticket.requesterEmail,
+                    ticket: {
+                        categoryId: ticket.categoryId,
+                        teamId: ticket.teamId,
+                        subject: ticket.subject,
+                        priority: ticket.priority,
+                        assigneeUserId: ticket.assigneeUserId,
+                        status: ticket.status,
+                    },
+                },
+                createdAt: now,
+            },
+        },
+        logger
+    );
+
+    // Queue assignment notification email (processed async)
+    if (ticket.assigneeEmail && ticket.assigneeUserId) {
+        await SqsService.sendMessage({
+            url: REMINDER_QUEUE,
+            messages: {
+                type: 'assignment',
+                ticketId: ticket.id,
+                assigneeEmail: ticket.assigneeEmail,
+                ticketNumber: ticket.ticketNumber,
+                subject: ticket.subject,
+                priority: ticket.priority,
+                requesterName: ticket.requesterName,
+                requesterEmail: ticket.requesterEmail,
+            },
+        });
+    }
+
+    return createResponse(ticket);
+};
+
+export const handler = middyfy(createTicket, middlewareConfig);

package/packages/functions/tickets/get.ts

@@ -0,0 +1,27 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, TICKETS_TABLE } from '../config';
+import { middyfy, NotFoundError, ValidationError } from '@xcelsior/lambda-http';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const getTicket = async (event: APIGatewayProxyEventV2) => {
+    const id = event.pathParameters?.id;
+    if (!id) {
+        throw new ValidationError('Ticket id is required', []);
+    }
+
+    const ticket = await DynamoDBService.getItem<any>(
+        {
+            tableName: TICKETS_TABLE,
+            key: id,
+        },
+        logger
+    );
+
+    if (!ticket) {
+        throw new NotFoundError('Ticket not found');
+    }
+
+    return createResponse(ticket);
+};
+
+export const handler = middyfy(getTicket, middlewareConfig);

package/packages/functions/tickets/list.ts

@@ -0,0 +1,63 @@
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { ZodError } from 'zod';
+import { createResponse, logger, middlewareConfig } from '../config';
+import { ticketListQuerySchema } from '../types';
+import {
+    buildTicketFilters,
+    decodeOffsetToken,
+    encodeOffsetToken,
+    getTicketIndex,
+    type TicketSearchDocument,
+} from '../search/ticketSearch';
+
+const listTickets = async (event: APIGatewayProxyEventV2) => {
+    let query;
+    try {
+        query = ticketListQuerySchema.parse(event.queryStringParameters || {});
+    } catch (error) {
+        if (error instanceof ZodError) {
+            throw new ValidationError('Invalid query parameters', error.errors);
+        }
+        throw error;
+    }
+
+    const { status, priority, categoryId, assigneeUserId, teamId, search, limit, nextToken } =
+        query;
+
+    const offset = decodeOffsetToken(nextToken);
+    logger.info('List tickets', {
+        status,
+        priority,
+        categoryId,
+        assigneeUserId,
+        teamId,
+        search,
+        limit,
+        offset,
+    });
+
+    const filters = buildTicketFilters({ status, priority, categoryId, assigneeUserId, teamId });
+    const index = await getTicketIndex();
+
+    const searchResult = await index.search<TicketSearchDocument>(search ?? '', {
+        filter: filters.length ? filters.join(' AND ') : undefined,
+        sort: ['createdAt:desc'],
+        limit,
+        offset,
+    });
+
+    return createResponse({
+        items: (searchResult.hits ?? []).map((hit: TicketSearchDocument) => ({
+            ...hit,
+            attachments: hit.attachments ?? [],
+        })),
+        nextToken:
+            typeof searchResult.estimatedTotalHits === 'number' &&
+            offset + (searchResult.hits?.length ?? 0) < searchResult.estimatedTotalHits
+                ? encodeOffsetToken(offset + (searchResult.hits?.length ?? 0))
+                : undefined,
+    });
+};
+
+export const handler = middyfy(listTickets, middlewareConfig);

package/packages/functions/tickets/searchSync.ts

@@ -0,0 +1,43 @@
+import type { DynamoDBStreamHandler } from 'aws-lambda';
+import { unmarshall } from '@aws-sdk/util-dynamodb';
+import { logger } from '../config';
+import { getTicketIndex, mapTicketToDocument } from '../search/ticketSearch';
+
+export const handler: DynamoDBStreamHandler = async (event) => {
+    const index = await getTicketIndex();
+
+    for (const record of event.Records) {
+        try {
+            if (record.eventName === 'REMOVE') {
+                const key = record.dynamodb?.Keys
+                    ? unmarshall(record.dynamodb.Keys as any)
+                    : undefined;
+                const id = (key as any)?.id;
+                if (id) {
+                    await index.deleteDocument(id);
+                    logger.info('Removed ticket from search index', { id });
+                }
+                continue;
+            }
+
+            const newImage = record.dynamodb?.NewImage;
+            if (!newImage) {
+                logger.warn('Stream record missing NewImage', { record });
+                continue;
+            }
+
+            const ticket = unmarshall(newImage as any);
+            const document = mapTicketToDocument(ticket);
+
+            await index.addDocuments([document], { primaryKey: 'id' });
+            logger.info('Upserted ticket into search index', { id: document.id });
+        } catch (error) {
+            logger.error('Failed to process ticket stream record for search', {
+                error,
+                eventName: record.eventName,
+                keys: record.dynamodb?.Keys,
+            });
+            throw error;
+        }
+    }
+};