sovrium 0.1.0 → 0.2.0

package/src/domain/models/api/params.ts

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { z } from 'zod'
+
+// ============================================================================
+// OpenAPI Path Parameter Schemas
+// ============================================================================
+
+/**
+ * Table ID path parameter
+ */
+export const tableIdParamSchema = z.object({
+  tableId: z.string().describe('Table identifier'),
+})
+
+/**
+ * Record ID path parameters (includes tableId)
+ */
+export const recordIdParamSchema = z.object({
+  tableId: z.string().describe('Table identifier'),
+  recordId: z.string().describe('Record identifier'),
+})
+
+/**
+ * Comment ID path parameters (includes tableId and recordId)
+ */
+export const commentIdParamSchema = z.object({
+  tableId: z.string().describe('Table identifier'),
+  recordId: z.string().describe('Record identifier'),
+  commentId: z.string().describe('Comment identifier'),
+})
+
+/**
+ * View ID path parameters (includes tableId)
+ */
+export const viewIdParamSchema = z.object({
+  tableId: z.string().describe('Table identifier'),
+  viewId: z.string().describe('View identifier'),
+})
+
+/**
+ * Activity ID path parameter
+ */
+export const activityIdParamSchema = z.object({
+  activityId: z.string().describe('Activity log identifier'),
+})
+
+// ============================================================================
+// OpenAPI Query Parameter Schemas
+// ============================================================================
+
+/**
+ * List records query parameters
+ */
+export const listRecordsQuerySchema = z.object({
+  page: z.string().optional().describe('Page number (1-indexed)'),
+  limit: z.string().optional().describe('Items per page'),
+  sort: z.string().optional().describe('Sort field'),
+  order: z.enum(['asc', 'desc']).optional().describe('Sort order'),
+  format: z.enum(['raw', 'display']).optional().describe('Field value format'),
+})
+
+/**
+ * Activity log query parameters
+ */
+export const activityQuerySchema = z.object({
+  page: z.string().optional().describe('Page number'),
+  pageSize: z.string().optional().describe('Items per page'),
+  tableId: z.string().optional().describe('Filter by table ID'),
+  action: z.enum(['create', 'update', 'delete', 'restore']).optional().describe('Filter by action'),
+})
+
+/**
+ * Create/update comment request body
+ */
+export const commentBodySchema = z.object({
+  content: z.string().min(1).max(10_000).describe('Comment text'),
+})

package/src/infrastructure/server/route-setup/openapi-routes/activity-routes.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { type OpenAPIHono, createRoute } from '@hono/zod-openapi'
+import {
+  getActivityLogResponseSchema,
+  listActivityLogsResponseSchema,
+} from '@/domain/models/api/activity'
+import { errorResponseSchema } from '@/domain/models/api/error'
+import { activityIdParamSchema, activityQuerySchema } from '@/domain/models/api/params'
+
+/**
+ * Register activity log routes for OpenAPI schema generation
+ */
+export function registerActivityRoutes(app: OpenAPIHono): void {
+  // GET /api/activity
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/activity',
+      summary: 'List activity logs',
+      description:
+        'Returns paginated activity logs with optional filtering by table or action type.',
+      operationId: 'listActivityLogs',
+      tags: ['activity'],
+      request: { query: activityQuerySchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: listActivityLogsResponseSchema } },
+          description: 'Activity logs',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // GET /api/activity/{activityId}
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/activity/{activityId}',
+      summary: 'Get activity log details',
+      description: 'Returns a single activity log entry with full change details.',
+      operationId: 'getActivityLog',
+      tags: ['activity'],
+      request: { params: activityIdParamSchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: getActivityLogResponseSchema } },
+          description: 'Activity log details',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+        404: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Activity not found',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+}

package/src/infrastructure/server/route-setup/openapi-routes/analytics-routes.ts

@@ -0,0 +1,176 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { type OpenAPIHono, createRoute } from '@hono/zod-openapi'
+import {
+  analyticsCollectSchema,
+  analyticsQuerySchema,
+  analyticsOverviewResponseSchema,
+  analyticsTopPagesResponseSchema,
+  analyticsTopReferrersResponseSchema,
+  analyticsDevicesResponseSchema,
+  analyticsCampaignsResponseSchema,
+} from '@/domain/models/api/analytics'
+import { successResponseSchema } from '@/domain/models/api/common'
+import { errorResponseSchema } from '@/domain/models/api/error'
+
+/**
+ * Register analytics routes for OpenAPI schema generation
+ */
+export function registerAnalyticsRoutes(app: OpenAPIHono): void {
+  // POST /api/analytics/collect
+  app.openapi(
+    createRoute({
+      method: 'post',
+      path: '/api/analytics/collect',
+      summary: 'Collect analytics event',
+      description: 'Records a page view event. Uses single-letter keys to minimize payload size.',
+      operationId: 'collectAnalytics',
+      tags: ['analytics'],
+      request: {
+        body: {
+          content: { 'application/json': { schema: analyticsCollectSchema } },
+        },
+      },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: successResponseSchema } },
+          description: 'Event collected',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Validation error',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // GET /api/analytics/overview
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/analytics/overview',
+      summary: 'Get analytics overview',
+      description: 'Returns summary statistics and time series data for the given date range.',
+      operationId: 'getAnalyticsOverview',
+      tags: ['analytics'],
+      request: { query: analyticsQuerySchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: analyticsOverviewResponseSchema } },
+          description: 'Analytics overview',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Invalid date range',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // GET /api/analytics/pages
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/analytics/pages',
+      summary: 'Get top pages',
+      description: 'Returns most visited pages with view counts and unique visitors.',
+      operationId: 'getAnalyticsTopPages',
+      tags: ['analytics'],
+      request: { query: analyticsQuerySchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: analyticsTopPagesResponseSchema } },
+          description: 'Top pages',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // GET /api/analytics/referrers
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/analytics/referrers',
+      summary: 'Get top referrers',
+      description: 'Returns traffic sources ranked by page views.',
+      operationId: 'getAnalyticsTopReferrers',
+      tags: ['analytics'],
+      request: { query: analyticsQuerySchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: analyticsTopReferrersResponseSchema } },
+          description: 'Top referrers',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // GET /api/analytics/devices
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/analytics/devices',
+      summary: 'Get device breakdown',
+      description: 'Returns visitor breakdown by device type, browser, and operating system.',
+      operationId: 'getAnalyticsDevices',
+      tags: ['analytics'],
+      request: { query: analyticsQuerySchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: analyticsDevicesResponseSchema } },
+          description: 'Device breakdown',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // GET /api/analytics/campaigns
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/analytics/campaigns',
+      summary: 'Get campaign breakdown',
+      description: 'Returns UTM campaign performance data.',
+      operationId: 'getAnalyticsCampaigns',
+      tags: ['analytics'],
+      request: { query: analyticsQuerySchema },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: analyticsCampaignsResponseSchema } },
+          description: 'Campaign breakdown',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+}

package/src/infrastructure/server/route-setup/openapi-routes/batch-routes.ts

@@ -0,0 +1,215 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { type OpenAPIHono, createRoute } from '@hono/zod-openapi'
+import { errorResponseSchema } from '@/domain/models/api/error'
+import { tableIdParamSchema } from '@/domain/models/api/params'
+import {
+  batchCreateRecordsRequestSchema,
+  batchDeleteRecordsRequestSchema,
+  batchRestoreRecordsRequestSchema,
+  batchUpdateRecordsRequestSchema,
+  upsertRecordsRequestSchema,
+} from '@/domain/models/api/request'
+import {
+  batchCreateRecordsResponseSchema,
+  batchDeleteRecordsResponseSchema,
+  batchRestoreRecordsResponseSchema,
+  batchUpdateRecordsResponseSchema,
+  upsertRecordsResponseSchema,
+} from '@/domain/models/api/tables'
+
+/**
+ * Register batch operation routes for OpenAPI schema generation
+ */
+export function registerBatchRoutes(app: OpenAPIHono): void {
+  // POST /api/tables/{tableId}/records/batch (create)
+  app.openapi(
+    createRoute({
+      method: 'post',
+      path: '/api/tables/{tableId}/records/batch',
+      summary: 'Batch create records',
+      description: 'Creates multiple records in a single request (up to 1000).',
+      operationId: 'batchCreateRecords',
+      tags: ['records'],
+      request: {
+        params: tableIdParamSchema,
+        body: {
+          content: { 'application/json': { schema: batchCreateRecordsRequestSchema } },
+        },
+      },
+      responses: {
+        201: {
+          content: { 'application/json': { schema: batchCreateRecordsResponseSchema } },
+          description: 'Records created',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Validation error',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+        404: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Table not found',
+        },
+      },
+    }),
+    (c) => c.json({} as never, 201)
+  )
+
+  // PATCH /api/tables/{tableId}/records/batch (update)
+  app.openapi(
+    createRoute({
+      method: 'patch',
+      path: '/api/tables/{tableId}/records/batch',
+      summary: 'Batch update records',
+      description: 'Updates multiple records in a single request (up to 100).',
+      operationId: 'batchUpdateRecords',
+      tags: ['records'],
+      request: {
+        params: tableIdParamSchema,
+        body: {
+          content: { 'application/json': { schema: batchUpdateRecordsRequestSchema } },
+        },
+      },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: batchUpdateRecordsResponseSchema } },
+          description: 'Records updated',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Validation error',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+        404: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Table not found',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // DELETE /api/tables/{tableId}/records/batch
+  app.openapi(
+    createRoute({
+      method: 'delete',
+      path: '/api/tables/{tableId}/records/batch',
+      summary: 'Batch delete records',
+      description: 'Soft-deletes multiple records in a single request (up to 100).',
+      operationId: 'batchDeleteRecords',
+      tags: ['records'],
+      request: {
+        params: tableIdParamSchema,
+        body: {
+          content: { 'application/json': { schema: batchDeleteRecordsRequestSchema } },
+        },
+      },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: batchDeleteRecordsResponseSchema } },
+          description: 'Records deleted',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Validation error',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+        404: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Table not found',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // POST /api/tables/{tableId}/records/batch/restore
+  app.openapi(
+    createRoute({
+      method: 'post',
+      path: '/api/tables/{tableId}/records/batch/restore',
+      summary: 'Batch restore deleted records',
+      description: 'Restores multiple soft-deleted records in a single request (up to 100).',
+      operationId: 'batchRestoreRecords',
+      tags: ['records'],
+      request: {
+        params: tableIdParamSchema,
+        body: {
+          content: { 'application/json': { schema: batchRestoreRecordsRequestSchema } },
+        },
+      },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: batchRestoreRecordsResponseSchema } },
+          description: 'Records restored',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Validation error',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+        404: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Table not found',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+
+  // POST /api/tables/{tableId}/records/upsert
+  app.openapi(
+    createRoute({
+      method: 'post',
+      path: '/api/tables/{tableId}/records/upsert',
+      summary: 'Upsert records',
+      description:
+        'Creates or updates records based on merge fields. Existing records matching the merge fields are updated; new records are created.',
+      operationId: 'upsertRecords',
+      tags: ['records'],
+      request: {
+        params: tableIdParamSchema,
+        body: {
+          content: { 'application/json': { schema: upsertRecordsRequestSchema } },
+        },
+      },
+      responses: {
+        200: {
+          content: { 'application/json': { schema: upsertRecordsResponseSchema } },
+          description: 'Records upserted',
+        },
+        400: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Validation error',
+        },
+        401: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Unauthorized',
+        },
+        404: {
+          content: { 'application/json': { schema: errorResponseSchema } },
+          description: 'Table not found',
+        },
+      },
+    }),
+    (c) => c.json({} as never)
+  )
+}

package/src/infrastructure/server/route-setup/openapi-routes/health-routes.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { type OpenAPIHono, createRoute } from '@hono/zod-openapi'
+import { healthResponseSchema } from '@/domain/models/api/health'
+
+/**
+ * Register health check routes for OpenAPI schema generation
+ */
+export function registerHealthRoutes(app: OpenAPIHono): void {
+  const healthRoute = createRoute({
+    method: 'get',
+    path: '/api/health',
+    summary: 'Health check endpoint',
+    description:
+      'Returns server health status. Used by monitoring tools and E2E tests to verify server is running.',
+    operationId: 'healthCheck',
+    tags: ['infrastructure'],
+    responses: {
+      200: {
+        content: { 'application/json': { schema: healthResponseSchema } },
+        description: 'Server is healthy',
+      },
+    },
+  })
+
+  app.openapi(healthRoute, (c) => {
+    return c.json({
+      status: 'ok' as const,
+      timestamp: new Date().toISOString(),
+      app: { name: 'Sovrium' },
+    })
+  })
+}