hazo_ihelp 2.0.6 → 2.1.0

package/dist/api/create_ihelp_handler.js

@@ -1,8 +1,13 @@
 /**
  * iHelp API Handler Factory
  *
- * Creates GET, POST, PATCH, and DELETE handlers for ihelp topic endpoints.
- * These handlers should be used in a Next.js API route.
+ * Creates GET, POST, PATCH, and DELETE handlers for hazo_ihelp_topics.
+ * Tags and context mappings are stored as JSON columns directly on the
+ * topics table — no separate join tables required.
+ *
+ * Every handler wraps its body with hazo_core's `withContext` so the
+ * correlation ID flows through every nested log call and downstream
+ * `fetchWithRequestId` outbound request.
  *
  * @example
  * ```typescript
@@ -17,44 +22,50 @@
  * });
  *
  * export { GET, POST };
- *
- * // app/api/ihelp/topics/[id]/route.ts
- * import { createIhelpHandler } from 'hazo_ihelp/api';
- * import { getHazoConnectSingleton } from 'hazo_connect/nextjs/setup';
- *
- * export const dynamic = 'force-dynamic';
- *
- * const { PATCH, DELETE } = createIhelpHandler({
- *   getHazoConnect: () => getHazoConnectSingleton(),
- * });
- *
- * export { PATCH, DELETE };
  * ```
  */
 import { NextResponse } from 'next/server';
 import { createCrudService } from 'hazo_connect/server';
+import { HazoError, HazoValidationError, HazoNotFoundError, generateRequestId, getCorrelationId, withContext, } from 'hazo_core';
+import { get_logger, set_logger } from '../utils/logger.js';
 // ============================================================================
 // Helper Functions
 // ============================================================================
-/** Generate a UUID v4 */
+/** Generate a UUID for DB primary keys. Strips the req_ prefix from generateRequestId(). */
 function generateUUID() {
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
+    return generateRequestId().slice(4);
 }
-/** No-op logger */
-const noopLogger = {
-    error: () => { },
-    warn: () => { },
-    info: () => { },
-    debug: () => { },
-};
 /** Create a standardized error response */
 function createErrorResponse(error, status) {
     return NextResponse.json({ success: false, error }, { status });
 }
+/** Wrap an error caught in a handler — log appropriately and return a response. */
+function handleError(logger, event, error) {
+    if (HazoError.is(error)) {
+        const status = error.httpStatus ?? 500;
+        if (status >= 500) {
+            logger.error(event, { code: error.code, message: error.message, context: error.context });
+        }
+        else {
+            logger.warn(event, { code: error.code, message: error.message });
+        }
+        return createErrorResponse(error.message, status);
+    }
+    logger.error(event, { error: error instanceof Error ? error.message : String(error) });
+    return createErrorResponse('Internal server error', 500);
+}
+/** Parse a JSON column value that may be a string or already parsed */
+function parseJsonColumn(value) {
+    if (typeof value === 'string') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return [];
+        }
+    }
+    return (value ?? []);
+}
 // ============================================================================
 // Handler Factory
 // ============================================================================
@@ -66,21 +77,22 @@ function createErrorResponse(error, status) {
  */
 export function createIhelpHandler(options) {
     const { getHazoConnect, getLogger } = options;
-    const logger = getLogger?.() || noopLogger;
+    if (getLogger) {
+        // Consumer override — wire through the package-level logger.
+        set_logger(getLogger());
+    }
+    const logger = get_logger();
     // ---------------------------------------------------------------------------
-    // Internal helper: assemble a full IhelpTopic with joined tags & context_keys
+    // Internal helper: normalise a DB row into a full IhelpTopic
     // ---------------------------------------------------------------------------
-    async function assembleTopicWithJoins(topicRow, adapter) {
-        const tagsService = createCrudService(adapter, 'ihelp_tags');
-        const contextMapService = createCrudService(adapter, 'ihelp_context_map');
-        const [tags, contextMappings] = await Promise.all([
-            tagsService.findBy({ topic_id: topicRow.id }),
-            contextMapService.findBy({ topic_id: topicRow.id }),
-        ]);
+    function normaliseTopic(row) {
+        const tags = parseJsonColumn(row.tags);
+        const contexts = parseJsonColumn(row.contexts);
         return {
-            ...topicRow,
+            ...row,
             tags,
-            context_keys: contextMappings.map((m) => m.context_key),
+            contexts,
+            context_keys: contexts.map((c) => c.key),
         };
     }
     // ---------------------------------------------------------------------------
@@ -97,76 +109,81 @@ export function createIhelpHandler(options) {
      *   - search       — ilike filter on title and description
      */
     async function GET(request) {
-        try {
-            const searchParams = request.nextUrl.searchParams;
-            const id = searchParams.get('id');
-            const context_key = searchParams.get('context_key');
-            const scope_id = searchParams.get('scope_id');
-            const category = searchParams.get('category');
-            const search = searchParams.get('search');
-            logger.debug('[hazo_ihelp] GET request', { id, context_key, scope_id, category, search });
-            const adapter = await getHazoConnect();
-            const topicsService = createCrudService(adapter, 'ihelp_topics');
-            // ---- Single topic fetch ----
-            if (id) {
-                const topic = await topicsService.findById(id);
-                if (!topic) {
-                    return createErrorResponse('Topic not found', 404);
+        return withContext({ correlationId: getCorrelationId() ?? generateRequestId() }, async () => {
+            try {
+                const searchParams = request.nextUrl.searchParams;
+                const id = searchParams.get('id');
+                const context_key = searchParams.get('context_key');
+                const scope_id = searchParams.get('scope_id');
+                const category = searchParams.get('category');
+                const search = searchParams.get('search');
+                logger.debug('topic.list.request', { id, context_key, scope_id, category, search });
+                const adapter = await getHazoConnect();
+                const topicsService = createCrudService(adapter, 'hazo_ihelp_topics');
+                // ---- Single topic fetch ----
+                if (id) {
+                    const topic = await topicsService.findById(id);
+                    if (!topic) {
+                        throw new HazoNotFoundError({
+                            code: 'HAZO_IHELP_TOPIC_NOT_FOUND',
+                            pkg: 'hazo_ihelp',
+                            message: 'Topic not found',
+                            context: { id },
+                        });
+                    }
+                    return NextResponse.json({ success: true, data: normaliseTopic(topic) });
                 }
-                const assembled = await assembleTopicWithJoins(topic, adapter);
-                return NextResponse.json({ success: true, data: assembled });
-            }
-            // ---- Context key lookup ----
-            if (context_key) {
-                const contextMapService = createCrudService(adapter, 'ihelp_context_map');
-                const mappings = await contextMapService.findBy({ context_key });
-                if (!mappings.length) {
-                    return NextResponse.json({ success: true, data: [] });
+                // ---- Context key lookup ----
+                if (context_key) {
+                    // Fetch all topics, filter by context key in application code
+                    // (works with both SQLite TEXT and PostgreSQL JSONB)
+                    const rows = await topicsService.list((qb) => {
+                        let q = qb;
+                        if (scope_id) {
+                            q = q.whereOr([
+                                { field: 'scope_id', operator: 'is', value: null },
+                                { field: 'scope_id', operator: 'eq', value: scope_id },
+                            ]);
+                        }
+                        return q;
+                    });
+                    const matched = rows
+                        .map(normaliseTopic)
+                        .filter((t) => t.contexts.some((c) => c.key === context_key))
+                        .sort((a, b) => {
+                        const pa = a.contexts.find((c) => c.key === context_key)?.priority ?? 0;
+                        const pb = b.contexts.find((c) => c.key === context_key)?.priority ?? 0;
+                        return pa - pb;
+                    });
+                    return NextResponse.json({ success: true, data: matched });
                 }
-                // Sort by priority ascending, then fetch matching topics
-                const sortedMappings = mappings.sort((a, b) => a.priority - b.priority);
-                const topicIds = sortedMappings.map((m) => m.topic_id);
-                const allTopics = [];
-                for (const topicId of topicIds) {
-                    const topic = await topicsService.findById(topicId);
-                    if (topic) {
-                        const assembled = await assembleTopicWithJoins(topic, adapter);
-                        allTopics.push(assembled);
+                // ---- List with optional filters ----
+                const rows = await topicsService.list((qb) => {
+                    let q = qb;
+                    if (scope_id) {
+                        q = q.whereOr([
+                            { field: 'scope_id', operator: 'is', value: null },
+                            { field: 'scope_id', operator: 'eq', value: scope_id },
+                        ]);
                     }
-                }
-                return NextResponse.json({ success: true, data: allTopics });
+                    if (category) {
+                        q = q.where('category', 'eq', category);
+                    }
+                    if (search) {
+                        q = q.whereOr([
+                            { field: 'title', operator: 'ilike', value: `%${search}%` },
+                            { field: 'description', operator: 'ilike', value: `%${search}%` },
+                        ]);
+                    }
+                    return q;
+                });
+                const assembled = rows.map(normaliseTopic);
+                return NextResponse.json({ success: true, data: assembled });
             }
-            // ---- List with optional filters ----
-            const rows = await topicsService.list((qb) => {
-                let q = qb;
-                if (scope_id) {
-                    // Topics where scope_id IS NULL or matches the given value
-                    q = q.whereOr([
-                        { field: 'scope_id', operator: 'is', value: null },
-                        { field: 'scope_id', operator: 'eq', value: scope_id },
-                    ]);
-                }
-                if (category) {
-                    q = q.where('category', 'eq', category);
-                }
-                if (search) {
-                    // ilike search on title and description
-                    q = q.whereOr([
-                        { field: 'title', operator: 'ilike', value: `%${search}%` },
-                        { field: 'description', operator: 'ilike', value: `%${search}%` },
-                    ]);
-                }
-                return q;
-            });
-            const assembled = await Promise.all(rows.map((row) => assembleTopicWithJoins(row, adapter)));
-            return NextResponse.json({ success: true, data: assembled });
-        }
-        catch (error) {
-            logger.error('[hazo_ihelp] GET error', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return createErrorResponse('Failed to fetch topics', 500);
-        }
+            catch (error) {
+                return handleError(logger, 'topic.list.failed', error);
+            }
+        });
     }
     // ---------------------------------------------------------------------------
     // POST handler — create a new topic
@@ -177,64 +194,69 @@ export function createIhelpHandler(options) {
      * Body: IhelpTopicInput
      */
     async function POST(request) {
-        try {
-            const body = (await request.json());
-            if (!body.title) {
-                return createErrorResponse('title is required', 400);
-            }
-            logger.debug('[hazo_ihelp] POST request', { title: body.title });
-            const adapter = await getHazoConnect();
-            const topicsService = createCrudService(adapter, 'ihelp_topics');
-            const tagsService = createCrudService(adapter, 'ihelp_tags');
-            const contextMapService = createCrudService(adapter, 'ihelp_context_map');
-            const topicId = generateUUID();
-            const now = new Date().toISOString();
-            // Insert topic
-            const inserted = await topicsService.insert({
-                id: topicId,
-                parent_id: body.parent_id ?? null,
-                scope_id: body.scope_id ?? null,
-                category: body.category ?? '',
-                title: body.title,
-                description: body.description ?? null,
-                content: body.content ?? null,
-                icon: body.icon ?? null,
-                sort_order: body.sort_order ?? 0,
-                is_published: body.is_published ?? false,
-                created_at: now,
-                changed_at: null,
-            });
-            const topicRow = Array.isArray(inserted) ? inserted[0] : inserted;
-            // Insert tags if provided
-            if (body.tags && body.tags.length > 0) {
-                const tagRows = body.tags.map((tag) => ({
-                    id: generateUUID(),
-                    topic_id: topicId,
-                    label: tag.label,
-                    variant: tag.variant ?? 'default',
-                    icon: tag.icon ?? null,
+        return withContext({ correlationId: getCorrelationId() ?? generateRequestId() }, async () => {
+            try {
+                const body = (await request.json());
+                if (!body.title) {
+                    throw new HazoValidationError({
+                        code: 'HAZO_IHELP_VALIDATION_ERROR',
+                        pkg: 'hazo_ihelp',
+                        message: 'title is required',
+                    });
+                }
+                logger.debug('topic.create.request', { title: body.title });
+                const adapter = await getHazoConnect();
+                const topicsService = createCrudService(adapter, 'hazo_ihelp_topics');
+                const topicId = generateUUID();
+                const now = new Date().toISOString();
+                // Build tags array
+                const tags = (body.tags ?? []).map((t) => ({
+                    label: t.label,
+                    variant: t.variant ?? 'default',
+                    icon: t.icon ?? null,
                 }));
-                await tagsService.insert(tagRows);
+                // Build contexts array — prefer explicit contexts, fall back to context_keys shorthand
+                let contexts;
+                if (body.contexts) {
+                    contexts = body.contexts.map((c) => ({
+                        key: c.key,
+                        priority: c.priority ?? 0,
+                    }));
+                }
+                else if (body.context_keys) {
+                    contexts = body.context_keys.map((key, i) => ({
+                        key,
+                        priority: i,
+                    }));
+                }
+                else {
+                    contexts = [];
+                }
+                const inserted = await topicsService.insert({
+                    id: topicId,
+                    parent_id: body.parent_id ?? null,
+                    scope_id: body.scope_id ?? null,
+                    category: body.category ?? '',
+                    title: body.title,
+                    description: body.description ?? null,
+                    content: body.content ?? null,
+                    icon: body.icon ?? null,
+                    sort_order: body.sort_order ?? 0,
+                    is_published: body.is_published ?? false,
+                    tags: JSON.stringify(tags),
+                    contexts: JSON.stringify(contexts),
+                    created_at: now,
+                    changed_at: null,
+                });
+                const topicRow = Array.isArray(inserted) ? inserted[0] : inserted;
+                const topic = normaliseTopic(topicRow);
+                logger.info('topic.created', { topic_id: topic.id, scope_id: topic.scope_id ?? null });
+                return NextResponse.json({ success: true, data: topic }, { status: 201 });
             }
-            // Insert context_keys if provided
-            if (body.context_keys && body.context_keys.length > 0) {
-                const mapRows = body.context_keys.map((key, index) => ({
-                    id: generateUUID(),
-                    topic_id: topicId,
-                    context_key: key,
-                    priority: index,
-                }));
-                await contextMapService.insert(mapRows);
+            catch (error) {
+                return handleError(logger, 'topic.create.failed', error);
             }
-            const assembled = await assembleTopicWithJoins(topicRow, adapter);
-            return NextResponse.json({ success: true, data: assembled }, { status: 201 });
-        }
-        catch (error) {
-            logger.error('[hazo_ihelp] POST error', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return createErrorResponse('Failed to create topic', 500);
-        }
+        });
     }
     // ---------------------------------------------------------------------------
     // PATCH handler — update an existing topic
@@ -246,93 +268,88 @@ export function createIhelpHandler(options) {
      * Body: Partial<IhelpTopicInput>
      */
     async function PATCH(request, context) {
-        try {
-            // Resolve id from params or query string
-            const { id: paramId } = await context.params;
-            let id = paramId;
-            if (!id) {
-                id = request.nextUrl.searchParams.get('id') ?? undefined;
-            }
-            if (!id) {
-                return createErrorResponse('id is required', 400);
-            }
-            const body = (await request.json());
-            logger.debug('[hazo_ihelp] PATCH request', { id });
-            const adapter = await getHazoConnect();
-            const topicsService = createCrudService(adapter, 'ihelp_topics');
-            const tagsService = createCrudService(adapter, 'ihelp_tags');
-            const contextMapService = createCrudService(adapter, 'ihelp_context_map');
-            // Build the patch payload (exclude relation fields)
-            const patch = { changed_at: new Date().toISOString() };
-            if (body.parent_id !== undefined)
-                patch.parent_id = body.parent_id;
-            if (body.scope_id !== undefined)
-                patch.scope_id = body.scope_id;
-            if (body.category !== undefined)
-                patch.category = body.category;
-            if (body.title !== undefined)
-                patch.title = body.title;
-            if (body.description !== undefined)
-                patch.description = body.description;
-            if (body.content !== undefined)
-                patch.content = body.content;
-            if (body.icon !== undefined)
-                patch.icon = body.icon;
-            if (body.sort_order !== undefined)
-                patch.sort_order = body.sort_order;
-            if (body.is_published !== undefined)
-                patch.is_published = body.is_published;
-            const updated = await topicsService.updateById(id, patch);
-            if (!updated || updated.length === 0) {
-                return createErrorResponse('Topic not found', 404);
-            }
-            const topicRow = updated[0];
-            // Replace tags if provided
-            if (body.tags !== undefined) {
-                // Delete existing tags one-by-one (deleteById targets the primary key)
-                const existingTags = await tagsService.findBy({ topic_id: id });
-                for (const tag of existingTags) {
-                    await tagsService.deleteById(tag.id);
+        return withContext({ correlationId: getCorrelationId() ?? generateRequestId() }, async () => {
+            try {
+                const { id: paramId } = await context.params;
+                let id = paramId;
+                if (!id) {
+                    id = request.nextUrl.searchParams.get('id') ?? undefined;
+                }
+                if (!id) {
+                    throw new HazoValidationError({
+                        code: 'HAZO_IHELP_VALIDATION_ERROR',
+                        pkg: 'hazo_ihelp',
+                        message: 'id is required',
+                    });
                 }
-                if (body.tags.length > 0) {
-                    const tagRows = body.tags.map((tag) => ({
-                        id: generateUUID(),
-                        topic_id: id,
-                        label: tag.label,
-                        variant: tag.variant ?? 'default',
-                        icon: tag.icon ?? null,
+                const body = (await request.json());
+                logger.debug('topic.update.request', { id });
+                const adapter = await getHazoConnect();
+                const topicsService = createCrudService(adapter, 'hazo_ihelp_topics');
+                // Build the patch payload
+                const patch = { changed_at: new Date().toISOString() };
+                if (body.parent_id !== undefined)
+                    patch.parent_id = body.parent_id;
+                if (body.scope_id !== undefined)
+                    patch.scope_id = body.scope_id;
+                if (body.category !== undefined)
+                    patch.category = body.category;
+                if (body.title !== undefined)
+                    patch.title = body.title;
+                if (body.description !== undefined)
+                    patch.description = body.description;
+                if (body.content !== undefined)
+                    patch.content = body.content;
+                if (body.icon !== undefined)
+                    patch.icon = body.icon;
+                if (body.sort_order !== undefined)
+                    patch.sort_order = body.sort_order;
+                if (body.is_published !== undefined)
+                    patch.is_published = body.is_published;
+                // Replace tags if provided
+                if (body.tags !== undefined) {
+                    const tags = body.tags.map((t) => ({
+                        label: t.label,
+                        variant: t.variant ?? 'default',
+                        icon: t.icon ?? null,
                     }));
-                    await tagsService.insert(tagRows);
+                    patch.tags = JSON.stringify(tags);
                 }
-            }
-            // Replace context_keys if provided
-            if (body.context_keys !== undefined) {
-                const existingMappings = await contextMapService.findBy({ topic_id: id });
-                for (const mapping of existingMappings) {
-                    await contextMapService.deleteById(mapping.id);
+                // Replace contexts if provided
+                if (body.contexts !== undefined) {
+                    const contexts = body.contexts.map((c) => ({
+                        key: c.key,
+                        priority: c.priority ?? 0,
+                    }));
+                    patch.contexts = JSON.stringify(contexts);
                 }
-                if (body.context_keys.length > 0) {
-                    const mapRows = body.context_keys.map((key, index) => ({
-                        id: generateUUID(),
-                        topic_id: id,
-                        context_key: key,
-                        priority: index,
+                else if (body.context_keys !== undefined) {
+                    const contexts = body.context_keys.map((key, i) => ({
+                        key,
+                        priority: i,
                     }));
-                    await contextMapService.insert(mapRows);
+                    patch.contexts = JSON.stringify(contexts);
                 }
+                const updated = await topicsService.updateById(id, patch);
+                if (!updated || updated.length === 0) {
+                    throw new HazoNotFoundError({
+                        code: 'HAZO_IHELP_TOPIC_NOT_FOUND',
+                        pkg: 'hazo_ihelp',
+                        message: 'Topic not found',
+                        context: { id },
+                    });
+                }
+                const topic = normaliseTopic(updated[0]);
+                logger.info('topic.updated', { topic_id: id });
+                return NextResponse.json({ success: true, data: topic });
             }
-            const assembled = await assembleTopicWithJoins(topicRow, adapter);
-            return NextResponse.json({ success: true, data: assembled });
-        }
-        catch (error) {
-            logger.error('[hazo_ihelp] PATCH error', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return createErrorResponse('Failed to update topic', 500);
-        }
+            catch (error) {
+                return handleError(logger, 'topic.update.failed', error);
+            }
+        });
     }
     // ---------------------------------------------------------------------------
-    // DELETE handler — remove a topic (CASCADE handles tags & context_map)
+    // DELETE handler — remove a topic
     // ---------------------------------------------------------------------------
     /**
      * DELETE handler
@@ -340,28 +357,31 @@ export function createIhelpHandler(options) {
      * Expects `id` as a URL search param or route segment param.
      */
     async function DELETE(request, context) {
-        try {
-            // Resolve id from params or query string
-            const { id: paramId } = await context.params;
-            let id = paramId;
-            if (!id) {
-                id = request.nextUrl.searchParams.get('id') ?? undefined;
+        return withContext({ correlationId: getCorrelationId() ?? generateRequestId() }, async () => {
+            try {
+                const { id: paramId } = await context.params;
+                let id = paramId;
+                if (!id) {
+                    id = request.nextUrl.searchParams.get('id') ?? undefined;
+                }
+                if (!id) {
+                    throw new HazoValidationError({
+                        code: 'HAZO_IHELP_VALIDATION_ERROR',
+                        pkg: 'hazo_ihelp',
+                        message: 'id is required',
+                    });
+                }
+                logger.debug('topic.delete.request', { id });
+                const adapter = await getHazoConnect();
+                const topicsService = createCrudService(adapter, 'hazo_ihelp_topics');
+                await topicsService.deleteById(id);
+                logger.info('topic.deleted', { topic_id: id });
+                return NextResponse.json({ success: true, data: null });
             }
-            if (!id) {
-                return createErrorResponse('id is required', 400);
+            catch (error) {
+                return handleError(logger, 'topic.delete.failed', error);
             }
-            logger.debug('[hazo_ihelp] DELETE request', { id });
-            const adapter = await getHazoConnect();
-            const topicsService = createCrudService(adapter, 'ihelp_topics');
-            await topicsService.deleteById(id);
-            return NextResponse.json({ success: true, data: null });
-        }
-        catch (error) {
-            logger.error('[hazo_ihelp] DELETE error', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return createErrorResponse('Failed to delete topic', 500);
-        }
+        });
     }
     return { GET, POST, PATCH, DELETE };
 }