sovrium 0.0.2

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

@@ -0,0 +1,231 @@
+/**
+ * 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'
+import { timestampSchema } from './common'
+
+// ============================================================================
+// User Schemas
+// ============================================================================
+
+/**
+ * User schema
+ *
+ * Represents a user in API responses.
+ * Based on Better Auth user model.
+ */
+export const userSchema = z
+  .object({
+    id: z.string().describe('Unique user identifier'),
+    email: z.email().describe('User email address'),
+    name: z.string().nullable().describe('User display name'),
+    image: z.url().nullable().optional().describe('User avatar URL'),
+    emailVerified: z.boolean().describe('Whether email is verified'),
+  })
+  .extend(timestampSchema.shape)
+
+/**
+ * User with role schema (for admin endpoints)
+ */
+export const userWithRoleSchema = userSchema.extend({
+  role: z.enum(['user', 'admin']).describe('User role'),
+  banned: z.boolean().optional().describe('Whether user is banned'),
+  banReason: z.string().nullable().optional().describe('Reason for ban'),
+  banExpiresAt: z.iso.datetime().nullable().optional().describe('Ban expiration'),
+})
+
+// ============================================================================
+// Session Schemas
+// ============================================================================
+
+/**
+ * Session schema
+ *
+ * Represents an authentication session.
+ */
+export const sessionSchema = z
+  .object({
+    id: z.string().describe('Session identifier'),
+    userId: z.string().describe('User ID this session belongs to'),
+    token: z.string().describe('Session token'),
+    expiresAt: z.iso.datetime().describe('Session expiration timestamp'),
+    ipAddress: z.string().nullable().optional().describe('IP address of session'),
+    userAgent: z.string().nullable().optional().describe('User agent string'),
+  })
+  .extend(timestampSchema.shape)
+
+/**
+ * Session with user schema
+ */
+export const sessionWithUserSchema = z.object({
+  session: sessionSchema,
+  user: userSchema,
+})
+
+// ============================================================================
+// Auth Response Schemas
+// ============================================================================
+
+/**
+ * Sign-in response schema
+ *
+ * Returned on successful email/password sign-in.
+ */
+export const signInResponseSchema = z.object({
+  user: userSchema.describe('Authenticated user data'),
+  session: sessionSchema.describe('New session data'),
+  token: z.string().optional().describe('Bearer token for API calls'),
+})
+
+/**
+ * Sign-up response schema
+ *
+ * Returned on successful user registration.
+ */
+export const signUpResponseSchema = z.object({
+  user: userSchema.describe('Newly created user data'),
+  session: sessionSchema.optional().describe('Session if auto-login enabled'),
+  token: z.string().optional().describe('Bearer token if auto-login enabled'),
+})
+
+/**
+ * Sign-out response schema
+ */
+export const signOutResponseSchema = z.object({
+  success: z.literal(true).describe('Sign-out succeeded'),
+})
+
+/**
+ * Session response schema
+ *
+ * Returned when fetching current session.
+ * Alias for sessionWithUserSchema for API clarity.
+ */
+export const getSessionResponseSchema = z.object({
+  session: sessionSchema,
+  user: userSchema,
+})
+
+/**
+ * List sessions response schema
+ */
+export const listSessionsResponseSchema = z.object({
+  sessions: z.array(sessionSchema).describe('List of active sessions'),
+})
+
+/**
+ * Revoke session response schema
+ */
+export const revokeSessionResponseSchema = z.object({
+  success: z.literal(true).describe('Session revoked successfully'),
+})
+
+// ============================================================================
+// Password Schemas
+// ============================================================================
+
+/**
+ * Password reset request response schema
+ */
+export const forgotPasswordResponseSchema = z.object({
+  success: z.literal(true).describe('Password reset email sent'),
+})
+
+/**
+ * Password reset response schema
+ */
+export const resetPasswordResponseSchema = z.object({
+  success: z.literal(true).describe('Password reset successful'),
+})
+
+/**
+ * Change password response schema
+ */
+export const changePasswordResponseSchema = z.object({
+  success: z.literal(true).describe('Password changed successfully'),
+})
+
+// ============================================================================
+// Verification Schemas
+// ============================================================================
+
+/**
+ * Email verification response schema
+ */
+export const verifyEmailResponseSchema = z.object({
+  user: userSchema.describe('User with verified email'),
+})
+
+/**
+ * Send verification email response schema
+ */
+export const sendVerificationEmailResponseSchema = z.object({
+  success: z.literal(true).describe('Verification email sent'),
+})
+
+// ============================================================================
+// Admin Schemas
+// ============================================================================
+
+/**
+ * Admin list users response schema
+ */
+export const adminListUsersResponseSchema = z.object({
+  users: z.array(userWithRoleSchema).describe('List of users'),
+  total: z.number().describe('Total user count'),
+  page: z.number().describe('Current page'),
+  limit: z.number().describe('Items per page'),
+})
+
+/**
+ * Admin get user response schema
+ */
+export const adminGetUserResponseSchema = z.object({
+  user: userWithRoleSchema.describe('User details'),
+})
+
+/**
+ * Admin update user response schema
+ */
+export const adminUpdateUserResponseSchema = z.object({
+  user: userWithRoleSchema.describe('Updated user'),
+})
+
+/**
+ * Admin delete user response schema
+ */
+export const adminDeleteUserResponseSchema = z.object({
+  success: z.literal(true).describe('User deleted'),
+})
+
+/**
+ * Admin ban user response schema
+ */
+export const adminBanUserResponseSchema = z.object({
+  user: userWithRoleSchema.describe('Banned user'),
+})
+
+/**
+ * Admin unban user response schema
+ */
+export const adminUnbanUserResponseSchema = z.object({
+  user: userWithRoleSchema.describe('Unbanned user'),
+})
+
+// ============================================================================
+// TypeScript Types
+// ============================================================================
+
+export type User = z.infer<typeof userSchema>
+export type UserWithRole = z.infer<typeof userWithRoleSchema>
+export type Session = z.infer<typeof sessionSchema>
+export type SessionWithUser = z.infer<typeof sessionWithUserSchema>
+export type SignInResponse = z.infer<typeof signInResponseSchema>
+export type SignUpResponse = z.infer<typeof signUpResponseSchema>
+export type SignOutResponse = z.infer<typeof signOutResponseSchema>
+export type GetSessionResponse = z.infer<typeof getSessionResponseSchema>
+export type ListSessionsResponse = z.infer<typeof listSessionsResponseSchema>

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

@@ -0,0 +1,60 @@
+/**
+ * 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'
+
+/**
+ * Pagination metadata schema
+ *
+ * Common pagination fields used across list endpoints.
+ */
+export const paginationSchema = z.object({
+  page: z.number().int().min(1).describe('Current page number (1-indexed)'),
+  limit: z.number().int().min(1).max(100).describe('Items per page'),
+  offset: z.number().int().min(0).describe('Offset from start of results'),
+  total: z.number().int().min(0).describe('Total number of items'),
+  totalPages: z.number().int().min(0).describe('Total number of pages'),
+  hasNextPage: z.boolean().describe('Whether there are more pages'),
+  hasPreviousPage: z.boolean().describe('Whether there are previous pages'),
+})
+
+/**
+ * Pagination query parameters schema
+ *
+ * Used for parsing pagination query parameters.
+ */
+export const paginationQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1).describe('Page number'),
+  limit: z.coerce.number().int().min(1).max(100).default(20).describe('Items per page'),
+})
+
+/**
+ * Timestamp metadata schema
+ *
+ * Common timestamp fields for audit trails.
+ */
+export const timestampSchema = z.object({
+  createdAt: z.iso.datetime().describe('ISO 8601 creation timestamp'),
+  updatedAt: z.iso.datetime().describe('ISO 8601 last update timestamp'),
+})
+
+/**
+ * Success response wrapper schema
+ *
+ * Standard wrapper for successful responses.
+ */
+export const successResponseSchema = z.object({
+  success: z.literal(true).describe('Operation success indicator'),
+})
+
+/**
+ * TypeScript types inferred from schemas
+ */
+export type Pagination = z.infer<typeof paginationSchema>
+export type PaginationQuery = z.infer<typeof paginationQuerySchema>
+export type Timestamps = z.infer<typeof timestampSchema>
+export type SuccessResponse = z.infer<typeof successResponseSchema>

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

@@ -0,0 +1,89 @@
+/**
+ * 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'
+
+/**
+ * Field validation error schema
+ *
+ * Represents a validation error on a specific field.
+ */
+export const fieldErrorSchema = z.object({
+  field: z.string().describe('Field name that failed validation'),
+  message: z.string().describe('Human-readable error message'),
+  code: z.string().optional().describe('Machine-readable error code'),
+})
+
+/**
+ * Validation error response schema
+ *
+ * Used for 400 Bad Request responses with field-level errors.
+ */
+export const validationErrorResponseSchema = z.object({
+  success: z.literal(false).describe('Operation failed'),
+  message: z.string().describe('General error message'),
+  code: z.literal('VALIDATION_ERROR').describe('Error type code'),
+  errors: z.array(fieldErrorSchema).describe('List of field-level validation errors'),
+})
+
+/**
+ * Generic error response schema
+ *
+ * Used for non-validation errors (401, 403, 404, 500, etc).
+ */
+export const errorResponseSchema = z.object({
+  success: z.literal(false).describe('Operation failed'),
+  error: z.string().optional().describe('Error type identifier'),
+  message: z.string().describe('Human-readable error message'),
+  code: z
+    .enum([
+      'UNAUTHORIZED',
+      'FORBIDDEN',
+      'NOT_FOUND',
+      'VALIDATION_ERROR',
+      'CONFLICT',
+      'RATE_LIMITED',
+      'INTERNAL_ERROR',
+      'SERVICE_UNAVAILABLE',
+    ])
+    .describe('Machine-readable error code'),
+  details: z.array(z.string()).optional().describe('Optional error details'),
+})
+
+/**
+ * Better Auth error response schema
+ *
+ * Better Auth returns errors in this format.
+ */
+export const betterAuthErrorSchema = z.object({
+  error: z
+    .object({
+      message: z.string().describe('Error message'),
+      status: z.number().optional().describe('HTTP status code'),
+    })
+    .describe('Error details'),
+})
+
+/**
+ * Combined API error schema
+ *
+ * Union of all possible error response formats.
+ */
+export const apiErrorSchema = z.union([
+  validationErrorResponseSchema,
+  errorResponseSchema,
+  betterAuthErrorSchema,
+])
+
+/**
+ * TypeScript types inferred from schemas
+ */
+export type FieldError = z.infer<typeof fieldErrorSchema>
+export type ValidationErrorResponse = z.infer<typeof validationErrorResponseSchema>
+export type ErrorResponse = z.infer<typeof errorResponseSchema>
+export type BetterAuthError = z.infer<typeof betterAuthErrorSchema>
+export type ApiError = z.infer<typeof apiErrorSchema>

package/src/domain/models/api/health.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 { z } from 'zod'
+
+/**
+ * Health check response schema
+ *
+ * Defines the shape of the health check API response.
+ * This schema is shared between:
+ * - Regular Hono routes (for runtime validation and RPC typing)
+ * - OpenAPI schema generation (for API documentation)
+ */
+export const healthResponseSchema = z.object({
+  status: z.literal('ok').describe('Server health status indicator'),
+  timestamp: z.iso
+    .datetime({
+      offset: true,
+      precision: 3,
+    })
+    .describe('ISO 8601 timestamp of the health check'),
+  app: z
+    .object({
+      name: z.string().describe('Application name from configuration'),
+    })
+    .describe('Application metadata'),
+})
+
+/**
+ * TypeScript type inferred from Zod schema
+ *
+ * Use this type for type-safe health check responses in application code.
+ */
+export type HealthResponse = z.infer<typeof healthResponseSchema>

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

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+
+/**
+ * API Schema Exports
+ *
+ * This module exports all Zod schemas used for API response validation
+ * and OpenAPI documentation generation.
+ *
+ * Schema Organization:
+ * - common: Pagination, timestamps, generic responses
+ * - error: Error response formats
+ * - health: Health check endpoint
+ * - auth: Authentication and authorization
+ * - tables: Table and record operations
+ * - request: Request input validation
+ */
+
+// Analytics schemas
+export * from './analytics'
+
+// Common schemas
+export * from './common'
+
+// Error schemas
+export * from './error'
+
+// Health check schemas
+export * from './health'
+
+// Authentication schemas
+export * from './auth'
+
+// Table and record schemas
+export * from './tables'
+
+// Request schemas (input validation)
+export * from './request'

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

@@ -0,0 +1,132 @@
+/**
+ * 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'
+import { fieldValueSchema } from './tables'
+
+// ============================================================================
+// Record Request Schemas
+// ============================================================================
+
+/**
+ * Create record request schema
+ *
+ * Validates the request body for creating a single record.
+ * Requires nested format: { fields: {...} }
+ */
+export const createRecordRequestSchema = z.object({
+  fields: z.record(z.string(), fieldValueSchema).optional().default({}),
+})
+
+/**
+ * Update record request schema
+ *
+ * Validates the request body for updating a record.
+ * Requires nested format: { fields: {...} }
+ */
+export const updateRecordRequestSchema = z.object({
+  fields: z.record(z.string(), fieldValueSchema).optional().default({}),
+})
+
+// ============================================================================
+// Batch Operation Request Schemas
+// ============================================================================
+
+/**
+ * Batch create records request schema
+ *
+ * Requires nested format: { fields: {...} } (Airtable style)
+ */
+export const batchCreateRecordsRequestSchema = z.object({
+  records: z
+    .array(
+      z.object({
+        fields: z.record(z.string(), fieldValueSchema).optional().default({}),
+      })
+    )
+    .min(1, 'At least one record is required')
+    .max(1000, 'Maximum 1000 records per batch'),
+  returnRecords: z.boolean().optional().default(false),
+})
+
+/**
+ * Batch update records request schema
+ *
+ * Requires nested format: { id: string, fields: {...} }
+ */
+export const batchUpdateRecordsRequestSchema = z.object({
+  records: z
+    .array(
+      z.object({
+        id: z
+          .union([z.string().min(1, 'Record ID is required'), z.number()])
+          .transform((val) => String(val)),
+        fields: z.record(z.string(), fieldValueSchema).optional().default({}),
+      })
+    )
+    .min(1, 'At least one record is required')
+    .max(100, 'Maximum 100 records per batch'),
+  returnRecords: z.boolean().optional().default(false),
+})
+
+/**
+ * Batch delete records request schema
+ */
+export const batchDeleteRecordsRequestSchema = z.object({
+  ids: z
+    .array(
+      z
+        .union([z.string().min(1, 'Record ID cannot be empty'), z.number()])
+        .transform((val) => String(val))
+    )
+    .min(1, 'At least one ID is required')
+    .max(100, 'Maximum 100 IDs per batch'),
+})
+
+/**
+ * Batch restore records request schema
+ */
+export const batchRestoreRecordsRequestSchema = z.object({
+  ids: z
+    .array(
+      z
+        .union([z.string().min(1, 'Record ID cannot be empty'), z.number()])
+        .transform((val) => String(val))
+    )
+    .min(1, 'At least one ID is required')
+    .max(100, 'Maximum 100 IDs per batch'),
+})
+
+/**
+ * Upsert records request schema
+ *
+ * Requires nested format: { fields: {...} }
+ */
+export const upsertRecordsRequestSchema = z.object({
+  records: z
+    .array(
+      z.object({
+        fields: z.record(z.string(), fieldValueSchema).optional().default({}),
+      })
+    )
+    .min(1, 'At least one record is required')
+    .max(100, 'Maximum 100 records per batch'),
+  fieldsToMergeOn: z.array(z.string()).min(1, 'At least one merge field is required'),
+  returnRecords: z.boolean().optional().default(false),
+})
+
+// ============================================================================
+// TypeScript Types
+// ============================================================================
+
+export type CreateRecordRequest = z.infer<typeof createRecordRequestSchema>
+export type UpdateRecordRequest = z.infer<typeof updateRecordRequestSchema>
+export type BatchCreateRecordsRequest = z.infer<typeof batchCreateRecordsRequestSchema>
+export type BatchUpdateRecordsRequest = z.infer<typeof batchUpdateRecordsRequestSchema>
+export type BatchDeleteRecordsRequest = z.infer<typeof batchDeleteRecordsRequestSchema>
+export type BatchRestoreRecordsRequest = z.infer<typeof batchRestoreRecordsRequestSchema>
+export type UpsertRecordsRequest = z.infer<typeof upsertRecordsRequestSchema>