sovrium 0.0.2 → 0.2.0

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

@@ -0,0 +1,131 @@
+/**
+ * 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'
+
+// ============================================================================
+// Comment Schemas
+// ============================================================================
+
+/**
+ * Comment user metadata schema
+ */
+export const commentUserSchema = z.object({
+  id: z.string().describe('User identifier'),
+  name: z.string().describe('User display name'),
+  email: z.string().describe('User email address'),
+  image: z.string().nullable().optional().describe('User avatar URL'),
+})
+
+/**
+ * Comment response schema
+ */
+export const commentSchema = z.object({
+  id: z.string().describe('Comment identifier'),
+  content: z.string().describe('Comment content'),
+  userId: z.string().describe('Author user ID'),
+  recordId: z.union([z.string(), z.number()]).describe('Parent record ID'),
+  tableId: z.union([z.string(), z.number()]).describe('Parent table ID'),
+  createdAt: z.string().describe('ISO 8601 creation timestamp'),
+  updatedAt: z.string().describe('ISO 8601 last update timestamp'),
+  user: commentUserSchema.describe('Comment author details'),
+})
+
+/**
+ * Comment pagination schema
+ */
+export const commentPaginationSchema = z.object({
+  total: z.number().int().describe('Total count of comments'),
+  limit: z.number().int().describe('Items returned'),
+  offset: z.number().int().describe('Items skipped'),
+  hasMore: z.boolean().describe('Whether more results exist'),
+})
+
+/**
+ * List comments response schema
+ *
+ * GET /api/tables/:tableId/records/:recordId/comments
+ */
+export const listCommentsResponseSchema = z.object({
+  comments: z.array(commentSchema).describe('List of comments'),
+  pagination: commentPaginationSchema.describe('Pagination metadata'),
+})
+
+/**
+ * Get single comment response schema
+ *
+ * GET /api/tables/:tableId/records/:recordId/comments/:commentId
+ */
+export const getCommentResponseSchema = commentSchema.describe('Single comment details')
+
+/**
+ * Create comment response schema
+ *
+ * POST /api/tables/:tableId/records/:recordId/comments
+ */
+export const createCommentResponseSchema = z.object({
+  comment: commentSchema.describe('Created comment'),
+})
+
+/**
+ * Update comment response schema
+ *
+ * PATCH /api/tables/:tableId/records/:recordId/comments/:commentId
+ */
+export const updateCommentResponseSchema = commentSchema.describe('Updated comment details')
+
+// ============================================================================
+// Record History Schemas
+// ============================================================================
+
+/**
+ * Record history entry schema
+ */
+export const recordHistoryEntrySchema = z.object({
+  id: z.string().describe('Activity log identifier'),
+  userId: z.string().optional().describe('User who performed the action'),
+  action: z.enum(['create', 'update', 'delete', 'restore']).describe('Action type'),
+  tableName: z.string().describe('Name of the affected table'),
+  recordId: z.union([z.string(), z.number()]).describe('ID of the affected record'),
+  changes: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe('Field changes (null for delete/restore)'),
+  createdAt: z.string().describe('ISO 8601 timestamp'),
+  user: z
+    .object({
+      id: z.string().describe('User identifier'),
+      name: z.string().describe('User display name'),
+      email: z.string().describe('User email address'),
+    })
+    .nullable()
+    .describe('User details (null for system activities)'),
+})
+
+/**
+ * Get record history response schema
+ *
+ * GET /api/tables/:tableId/records/:recordId/history
+ */
+export const getRecordHistoryResponseSchema = z.object({
+  history: z.array(recordHistoryEntrySchema).describe('List of history entries'),
+  pagination: z
+    .object({
+      total: z.number().int().describe('Total activity count'),
+      limit: z.number().int().describe('Items returned'),
+      offset: z.number().int().describe('Items skipped'),
+    })
+    .optional()
+    .describe('Pagination metadata'),
+})
+
+// ============================================================================
+// TypeScript Types
+// ============================================================================
+
+export type Comment = z.infer<typeof commentSchema>
+export type RecordHistoryEntry = z.infer<typeof recordHistoryEntrySchema>

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

@@ -20,6 +20,9 @@
  * - request: Request input validation
  */
 
+// Activity log schemas
+export * from './activity'
+
 // Analytics schemas
 export * from './analytics'
 
@@ -35,8 +38,14 @@ export * from './health'
 // Authentication schemas
 export * from './auth'
 
+// Comment and history schemas
+export * from './comments'
+
 // Table and record schemas
 export * from './tables'
 
+// OpenAPI parameter schemas
+export * from './params'
+
 // Request schemas (input validation)
 export * from './request'

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)
+  )
+}