@xcelsior/support-api 0.1.1

package/cdk.context.json

@@ -0,0 +1,6 @@
+{
+    "hosted-zone:account=192933325589:domainName=xcelsior.co:region=ap-southeast-2": {
+        "Id": "/hostedzone/Z08595403217R035ZUO3M",
+        "Name": "xcelsior.co."
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xcelsior/support-api",
+  "version": "0.1.1",
+  "type": "module",
+  "files": [
+    "packages/**",
+    "stacks/**",
+    "docs/**",
+    "*.json",
+    "sst.config.ts"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.888.0",
+    "@aws-sdk/client-s3": "^3.888.0",
+    "@aws-sdk/client-sqs": "^3.888.0",
+    "@aws-sdk/lib-dynamodb": "^3.888.0",
+    "@aws-sdk/util-dynamodb": "^3.888.0",
+    "meilisearch": "^0.55.0",
+    "sst": "^2.40.3",
+    "zod": "^3.22.4",
+    "@types/aws-lambda": "^8.10.152",
+    "aws-cdk-lib": "2.201.0",
+    "constructs": "10.3.0",
+    "dotenv": "^17.2.1",
+    "typescript": "^5.3.3",
+    "@tsconfig/node18": "^18.2.2",
+    "@types/node": "^20.11.16",
+    "@xcelsior/aws": "1.0.3",
+    "@xcelsior/lambda-http": "1.0.5",
+    "@xcelsior/monitoring": "1.0.4",
+    "@xcelsior/email": "1.0.2",
+    "@xcelsior/support-client": "1.0.0"
+  },
+  "scripts": {
+    "dev": "sst dev --stage dev --mode basic",
+    "build": "sst build",
+    "deploy": "sst deploy",
+    "remove": "sst remove",
+    "console": "sst console",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/packages/functions/attachments/generateUploadUrl.ts

@@ -0,0 +1,55 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import {
+    ATTACHMENTS_BUCKET,
+    CLOUDFRONT_DOMAIN,
+    createResponse,
+    logger,
+    middlewareConfig,
+} from '../config';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import { ZodError } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { S3Service } from '@xcelsior/aws/src/s3';
+import { attachmentUploadRequestSchema } from '../types';
+
+const generateUploadUrl = async (event: APIGatewayProxyEventV2) => {
+    let parsedBody;
+    try {
+        parsedBody = attachmentUploadRequestSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof ZodError) {
+            throw new ValidationError('Invalid request data', error.errors);
+        }
+        throw error;
+    }
+
+    const { fileName, contentType } = parsedBody;
+
+    const fileExtension = fileName.split('.').pop()?.toLowerCase() || 'bin';
+    const key = `attachments/${randomUUID()}.${fileExtension}`;
+
+    logger.info('Generating presigned upload URL for attachment', {
+        fileName,
+        contentType,
+        key,
+    });
+
+    const uploadUrl = await S3Service.generatePresignedUploadUrl(
+        ATTACHMENTS_BUCKET,
+        key,
+        contentType,
+        300
+    );
+
+    // The final public URL where the attachment will be accessible via CloudFront
+    const attachmentUrl = `https://${CLOUDFRONT_DOMAIN}/${key}`;
+
+    return createResponse({
+        uploadUrl,
+        attachmentUrl,
+        key,
+        expiresIn: 300,
+    });
+};
+
+export const handler = middyfy(generateUploadUrl, middlewareConfig);

package/packages/functions/categories/archive.ts

@@ -0,0 +1,57 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, CATEGORIES_TABLE } from '../config';
+import { middyfy, NotFoundError, ValidationError } from '@xcelsior/lambda-http';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const archiveCategory = async (event: APIGatewayProxyEventV2) => {
+    const id = event.pathParameters?.id;
+    if (!id) {
+        throw new ValidationError('Category id is required', []);
+    }
+
+    const existing = await DynamoDBService.getItem<any>(
+        {
+            tableName: CATEGORIES_TABLE,
+            key: id,
+        },
+        logger
+    );
+
+    if (!existing) {
+        throw new NotFoundError('Category not found');
+    }
+
+    const archivedAt = new Date().toISOString();
+
+    const updated = await DynamoDBService.updateItem(
+        {
+            tableName: CATEGORIES_TABLE,
+            key: { id },
+            updateExpression:
+                'SET archivedAt = :archivedAt, isActive = :isActive, updatedAt = :updatedAt',
+            expressionAttributeValues: {
+                ':archivedAt': archivedAt,
+                ':isActive': false,
+                ':updatedAt': archivedAt,
+            },
+        },
+        logger
+    );
+
+    logger.info('Archive category', { id });
+
+    const safeUpdated =
+        (updated as any) ??
+        ({
+            id,
+            archivedAt,
+            isActive: false,
+        } as const);
+
+    return createResponse({
+        ...safeUpdated,
+        isActive: false,
+    });
+};
+
+export const handler = middyfy(archiveCategory, middlewareConfig);

package/packages/functions/categories/create.ts

@@ -0,0 +1,44 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, CATEGORIES_TABLE } from '../config';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import { categoryCreateSchema } from '../types';
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const createCategory = async (event: APIGatewayProxyEventV2) => {
+    let payload;
+    try {
+        payload = categoryCreateSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid category payload', error.errors);
+        }
+        throw error;
+    }
+
+    const now = new Date().toISOString();
+    const category = {
+        id: randomUUID(),
+        name: payload.name,
+        isActive: true,
+        createdAt: now,
+        updatedAt: now,
+    };
+
+    logger.info('Create category', { categoryId: category.id });
+
+    await DynamoDBService.putItem(
+        {
+            tableName: CATEGORIES_TABLE,
+            item: category,
+        },
+        logger
+    );
+
+    return createResponse({
+        ...category,
+    });
+};
+
+export const handler = middyfy(createCategory, middlewareConfig);

package/packages/functions/categories/list.ts

@@ -0,0 +1,29 @@
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+import { middyfy } from '@xcelsior/lambda-http';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { CATEGORIES_TABLE, createResponse, logger, middlewareConfig } from '../config';
+
+const listCategories = async (event: APIGatewayProxyEventV2) => {
+    logger.info('List categories');
+
+    const result = await DynamoDBService.scanItems<any>(
+        {
+            tableName: CATEGORIES_TABLE,
+        },
+        logger
+    );
+
+    const items = result.items.map((item) => ({
+        ...item,
+        isActive: !item.archivedAt,
+    }));
+
+    return createResponse({
+        items,
+        nextToken: result.nextToken
+            ? Buffer.from(JSON.stringify(result.nextToken)).toString('base64')
+            : undefined,
+    });
+};
+
+export const handler = middyfy(listCategories, middlewareConfig);

package/packages/functions/categories/update.ts

@@ -0,0 +1,73 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, CATEGORIES_TABLE } from '../config';
+import { middyfy, NotFoundError, ValidationError } from '@xcelsior/lambda-http';
+import { categoryUpdateSchema } from '../types';
+import { z } from 'zod';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const updateCategory = async (event: APIGatewayProxyEventV2) => {
+    let payload;
+    try {
+        payload = categoryUpdateSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid category update payload', error.errors);
+        }
+        throw error;
+    }
+
+    const id = event.pathParameters?.id;
+    if (!id) {
+        throw new ValidationError('Category id is required', []);
+    }
+
+    const existing = await DynamoDBService.getItem<any>(
+        {
+            tableName: CATEGORIES_TABLE,
+            key: id,
+        },
+        logger
+    );
+
+    if (!existing) {
+        throw new NotFoundError('Category not found');
+    }
+
+    const updates: string[] = [];
+    const values: Record<string, any> = {};
+    const names: Record<string, string> = {};
+
+    if (payload.name) {
+        updates.push('#name = :name');
+        values[':name'] = payload.name;
+        names['#name'] = 'name';
+    }
+
+    if (payload.isActive !== undefined) {
+        updates.push('isActive = :isActive');
+        values[':isActive'] = payload.isActive;
+    }
+
+    updates.push('updatedAt = :updatedAt');
+    values[':updatedAt'] = new Date().toISOString();
+
+    const updated = await DynamoDBService.updateItem(
+        {
+            tableName: CATEGORIES_TABLE,
+            key: { id },
+            updateExpression: `SET ${updates.join(', ')}`,
+            expressionAttributeValues: values,
+            expressionAttributeNames: Object.keys(names).length ? names : undefined,
+        },
+        logger
+    );
+
+    const safeUpdated = (updated as any) ?? { id, isActive: payload.isActive ?? existing.isActive };
+
+    return createResponse({
+        ...safeUpdated,
+        isActive: safeUpdated?.isActive !== false,
+    });
+};
+
+export const handler = middyfy(updateCategory, middlewareConfig);

package/packages/functions/config/get.ts

@@ -0,0 +1,40 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, SUPPORT_CONFIG_TABLE } from '../config';
+import { middyfy } from '@xcelsior/lambda-http';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const CONFIG_ID = 'support-config';
+
+const getSupportConfig = async (_event: APIGatewayProxyEventV2) => {
+    logger.info('Get support config');
+
+    const existing = await DynamoDBService.getItem<{
+        id: string;
+        notification?: { emailOnAssignment?: boolean };
+        sla?: { low?: number; medium?: number; high?: number; critical?: number };
+        updatedAt?: string;
+    }>(
+        {
+            tableName: SUPPORT_CONFIG_TABLE,
+            key: CONFIG_ID,
+        },
+        logger
+    );
+
+    if (!existing) {
+        return createResponse({
+            id: CONFIG_ID,
+            notification: { emailOnAssignment: true },
+            sla: { low: 7, medium: 5, high: 3, critical: 1 },
+        });
+    }
+
+    return createResponse({
+        id: existing.id,
+        notification: existing.notification ?? { emailOnAssignment: true },
+        sla: existing.sla ?? { low: 7, medium: 5, high: 3, critical: 1 },
+        updatedAt: existing.updatedAt,
+    });
+};
+
+export const handler = middyfy(getSupportConfig, middlewareConfig);

package/packages/functions/config/update.ts

@@ -0,0 +1,44 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, SUPPORT_CONFIG_TABLE } from '../config';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import { supportConfigSchema } from '../types';
+import { z } from 'zod';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const CONFIG_ID = 'support-config';
+
+const updateSupportConfig = async (event: APIGatewayProxyEventV2) => {
+    let payload;
+    try {
+        payload = supportConfigSchema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid support config', error.errors);
+        }
+        throw error;
+    }
+
+    logger.info('Update support config');
+
+    const now = new Date().toISOString();
+    const settings = {
+        notification: payload.notification ?? { emailOnAssignment: true },
+        sla: payload.sla ?? { low: 7, medium: 5, high: 3, critical: 1 },
+    };
+
+    await DynamoDBService.putItem(
+        {
+            tableName: SUPPORT_CONFIG_TABLE,
+            item: {
+                id: CONFIG_ID,
+                ...settings,
+                updatedAt: now,
+            },
+        },
+        logger
+    );
+
+    return createResponse({ id: CONFIG_ID, ...settings, updatedAt: now });
+};
+
+export const handler = middyfy(updateSupportConfig, middlewareConfig);

package/packages/functions/config.ts

@@ -0,0 +1,40 @@
+import { Table } from 'sst/node/table';
+import { Bucket } from 'sst/node/bucket';
+import { Queue } from 'sst/node/queue';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { createLogger, createTracer } from '@xcelsior/lambda-http';
+import type { ApiResponse } from './types';
+
+export const SUPPORT_CONFIG_TABLE = Table['support-config'].tableName;
+export const CATEGORIES_TABLE = Table['support-categories'].tableName;
+export const TEAMS_TABLE = Table['support-teams'].tableName;
+export const TICKETS_TABLE = Table['support-tickets'].tableName;
+export const TICKET_EVENTS_TABLE = Table['support-ticket-events'].tableName;
+export const ATTACHMENTS_BUCKET = Bucket['support-attachments'].bucketName;
+export const REMINDER_QUEUE = Queue['support-reminder-queue'].queueUrl;
+export const CLOUDFRONT_DOMAIN = process.env.CLOUDFRONT_DOMAIN!;
+
+const client = new DynamoDBClient({});
+export const dynamoDb = DynamoDBDocumentClient.from(client, {
+    marshallOptions: { removeUndefinedValues: true },
+});
+
+export function createResponse<T>(
+    data?: T,
+    error?: { code: string; message: string },
+    pagination?: { nextPageToken?: string }
+): ApiResponse<T> {
+    return { data, error, pagination };
+}
+
+export const logger = createLogger('@xcelsior/support');
+const tracer = createTracer('@xcelsior/support');
+
+export const middlewareConfig = {
+    logger,
+    tracer,
+    cors: {
+        origin: '*',
+    },
+};

package/packages/functions/events/list.ts

@@ -0,0 +1,48 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { createResponse, logger, middlewareConfig, TICKET_EVENTS_TABLE } from '../config';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import { DynamoDBService } from '@xcelsior/aws/src/dynamodb';
+
+const listTicketEvents = async (event: APIGatewayProxyEventV2) => {
+    const ticketId = event.pathParameters?.id;
+    if (!ticketId) {
+        throw new ValidationError('Ticket id is required', []);
+    }
+
+    const limit = event.queryStringParameters?.limit
+        ? Number.parseInt(event.queryStringParameters.limit, 10)
+        : 50;
+
+    const nextToken = event.queryStringParameters?.nextToken;
+
+    logger.info('List ticket events', { ticketId, limit });
+
+    const result = await DynamoDBService.queryItems(
+        {
+            tableName: TICKET_EVENTS_TABLE,
+            indexName: 'TicketIndex',
+            keyConditionExpression: 'ticketId = :ticketId',
+            expressionAttributeValues: {
+                ':ticketId': ticketId,
+            },
+            scanIndexForward: false, // Sort descending (newest first)
+            limit,
+            exclusiveStartKey: nextToken
+                ? JSON.parse(Buffer.from(nextToken, 'base64').toString())
+                : undefined,
+        },
+        logger
+    );
+
+    const events = result.items ?? [];
+    const lastEvaluatedKey = result.nextToken;
+
+    return createResponse({
+        items: events,
+        nextToken: lastEvaluatedKey
+            ? Buffer.from(JSON.stringify(lastEvaluatedKey)).toString('base64')
+            : undefined,
+    });
+};
+
+export const handler = middyfy(listTicketEvents, middlewareConfig);

package/packages/functions/search/ticketSearch.ts

@@ -0,0 +1,128 @@
+import { MeiliSearch, type Index } from 'meilisearch';
+import { logger } from '../config';
+
+export type TicketSearchDocument = {
+    id: string;
+    ticketNumber?: number;
+    subject: string;
+    description: string;
+    status: string;
+    priority: string | null;
+    categoryId: string | null;
+    teamId: string | null;
+    assigneeUserId: string | null;
+    requesterName: string;
+    requesterEmail: string;
+    attachments: string[];
+    reminderAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+
+type TicketFilterInput = Partial<
+    Pick<TicketSearchDocument, 'status' | 'priority' | 'categoryId' | 'assigneeUserId' | 'teamId'>
+>;
+
+const meilisearchHost = process.env.MEILISEARCH_HOST;
+const meilisearchApiKey = process.env.MEILISEARCH_API_KEY;
+const ticketSearchIndex = process.env.TICKETS_SEARCH_INDEX ?? 'support-tickets';
+
+let indexPromise: Promise<Index<TicketSearchDocument>> | null = null;
+let settingsPromise: Promise<void> | null = null;
+
+const escapeFilterValue = (value: string) => value.replace(/"/g, '\\"');
+
+export const getTicketIndex = async (): Promise<Index<TicketSearchDocument>> => {
+    if (!meilisearchHost || !meilisearchApiKey) {
+        throw new Error('Meilisearch is not configured');
+    }
+
+    if (!indexPromise) {
+        const client = new MeiliSearch({
+            host: meilisearchHost,
+            apiKey: meilisearchApiKey,
+        });
+        indexPromise = Promise.resolve(client.index<TicketSearchDocument>(ticketSearchIndex));
+    }
+
+    const index = await indexPromise;
+
+    if (!settingsPromise) {
+        settingsPromise = index
+            .updateSettings({
+                filterableAttributes: [
+                    'status',
+                    'priority',
+                    'categoryId',
+                    'assigneeUserId',
+                    'teamId',
+                ],
+                sortableAttributes: ['createdAt', 'updatedAt'],
+            })
+            .then(() => undefined)
+            .catch((error: unknown) => {
+                settingsPromise = null;
+                logger.error('Failed to configure ticket search index', { error });
+                throw error;
+            });
+    }
+
+    await settingsPromise;
+    return index;
+};
+
+export const buildTicketFilters = (filters: TicketFilterInput) => {
+    const parts: string[] = [];
+
+    if (filters.status) {
+        parts.push(`status = "${escapeFilterValue(filters.status)}"`);
+    }
+    if (filters.priority) {
+        parts.push(`priority = "${escapeFilterValue(filters.priority)}"`);
+    }
+    if (filters.categoryId) {
+        parts.push(`categoryId = "${escapeFilterValue(filters.categoryId)}"`);
+    }
+    if (filters.assigneeUserId) {
+        parts.push(`assigneeUserId = "${escapeFilterValue(filters.assigneeUserId)}"`);
+    }
+    if (filters.teamId) {
+        parts.push(`teamId = "${escapeFilterValue(filters.teamId)}"`);
+    }
+
+    return parts;
+};
+
+export const decodeOffsetToken = (token?: string) => {
+    if (!token) return 0;
+    try {
+        const parsed = JSON.parse(Buffer.from(token, 'base64').toString('utf8'));
+        if (typeof parsed?.offset === 'number') {
+            return parsed.offset;
+        }
+    } catch (error) {
+        logger.warn('Failed to decode ticket list token, defaulting to offset 0', { error });
+    }
+    return 0;
+};
+
+export const encodeOffsetToken = (offset: number) =>
+    Buffer.from(JSON.stringify({ offset })).toString('base64');
+
+export const mapTicketToDocument = (ticket: any): TicketSearchDocument => ({
+    id: ticket.id,
+    ticketNumber: ticket.ticketNumber,
+    subject: ticket.subject ?? '',
+    description: ticket.description ?? '',
+    status: ticket.status ?? 'Unknown',
+    priority: ticket.priority ?? null,
+    categoryId: ticket.categoryId ?? null,
+    teamId: ticket.teamId ?? null,
+    assigneeUserId: ticket.assigneeUserId ?? null,
+    requesterName: ticket.requesterName ?? '',
+    requesterEmail: ticket.requesterEmail ?? '',
+    attachments: Array.isArray(ticket.attachments) ? ticket.attachments : [],
+    reminderAt: ticket.reminderAt ?? null,
+    createdAt: ticket.createdAt ?? new Date().toISOString(),
+    updatedAt: ticket.updatedAt ?? ticket.createdAt ?? new Date().toISOString(),
+});