sovrium 0.0.2

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

@@ -0,0 +1,444 @@
+/**
+ * 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 { paginationSchema, timestampSchema } from './common'
+
+// ============================================================================
+// Field Schemas
+// ============================================================================
+
+/**
+ * Base field schema
+ *
+ * Common properties for all field types.
+ */
+export const baseFieldSchema = z.object({
+  id: z.string().describe('Field identifier'),
+  name: z.string().describe('Field name'),
+  type: z.string().describe('Field type'),
+  required: z.boolean().optional().describe('Whether field is required'),
+  unique: z.boolean().optional().describe('Whether field must be unique'),
+  indexed: z.boolean().optional().describe('Whether field is indexed'),
+  description: z.string().optional().describe('Field description'),
+})
+
+/**
+ * Field value schema (for record data)
+ *
+ * Represents a value in a record field.
+ */
+export const fieldValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.unknown()),
+  z.record(z.string(), z.unknown()),
+])
+
+/**
+ * Formatted field value schema (for display formatting)
+ *
+ * When format=display is requested, fields may include both value and displayValue.
+ */
+export const formattedFieldValueSchema = z.union([
+  fieldValueSchema,
+  z.object({
+    value: fieldValueSchema,
+    displayValue: z.string().optional(),
+  }),
+])
+
+// ============================================================================
+// Table Schemas
+// ============================================================================
+
+/**
+ * Table schema
+ *
+ * Represents a table definition in API responses.
+ */
+export const tableSchema = z
+  .object({
+    id: z.string().describe('Table identifier'),
+    name: z.string().describe('Table name'),
+    description: z.string().optional().describe('Table description'),
+    fields: z.array(baseFieldSchema).describe('Table fields'),
+    primaryKey: z.string().optional().describe('Primary key field'),
+    views: z.array(z.unknown()).describe('Table views'),
+    permissions: z
+      .object({
+        read: z
+          .union([z.array(z.string()).readonly(), z.literal('all'), z.literal('authenticated')])
+          .optional(),
+        create: z
+          .union([z.array(z.string()).readonly(), z.literal('all'), z.literal('authenticated')])
+          .optional(),
+        update: z
+          .union([z.array(z.string()).readonly(), z.literal('all'), z.literal('authenticated')])
+          .optional(),
+        delete: z
+          .union([z.array(z.string()).readonly(), z.literal('all'), z.literal('authenticated')])
+          .optional(),
+      })
+      .optional()
+      .describe('Table permissions'),
+  })
+  .extend(timestampSchema.shape)
+
+/**
+ * Table summary schema (for list endpoints)
+ */
+export const tableSummarySchema = z
+  .object({
+    id: z.string().describe('Table identifier'),
+    name: z.string().describe('Table name'),
+    description: z.string().optional().describe('Table description'),
+    fieldCount: z.number().describe('Number of fields'),
+    recordCount: z.number().optional().describe('Number of records'),
+  })
+  .extend(timestampSchema.shape)
+
+// ============================================================================
+// Record Schemas
+// ============================================================================
+
+/**
+ * Record schema (Airtable-style)
+ *
+ * Represents a record in a table.
+ * User-defined fields are nested under the `fields` property.
+ * System fields (id, createdAt, updatedAt) remain at root level.
+ */
+/**
+ * User reference schema for authorship fields
+ */
+export const userRefSchema = z.object({
+  id: z.string().describe('User identifier'),
+  name: z.string().optional().describe('User display name'),
+  email: z.string().optional().describe('User email address'),
+})
+
+export const recordSchema = z
+  .object({
+    id: z.union([z.string(), z.number()]).describe('Record identifier'),
+    fields: z
+      .record(z.string(), formattedFieldValueSchema)
+      .describe('User-defined field values (may include display formatting)'),
+    createdBy: z.string().optional().describe('User who created the record'),
+    updatedBy: z.string().optional().describe('User who last updated the record'),
+    deletedBy: userRefSchema.optional().describe('User who deleted the record'),
+  })
+  .extend(timestampSchema.shape)
+
+// ============================================================================
+// Table API Response Schemas
+// ============================================================================
+
+/**
+ * List tables response schema
+ */
+export const listTablesResponseSchema = z.object({
+  tables: z.array(tableSummarySchema).describe('List of tables'),
+  pagination: paginationSchema.optional().describe('Pagination metadata'),
+})
+
+/**
+ * Get table response schema
+ */
+export const getTableResponseSchema = z.object({
+  table: tableSchema.describe('Table details'),
+})
+
+/**
+ * Create table response schema
+ */
+export const createTableResponseSchema = z.object({
+  table: tableSchema.describe('Created table'),
+})
+
+/**
+ * Update table response schema
+ */
+export const updateTableResponseSchema = z.object({
+  table: tableSchema.describe('Updated table'),
+})
+
+/**
+ * Delete table response schema
+ */
+export const deleteTableResponseSchema = z.object({
+  success: z.literal(true).describe('Table deleted'),
+})
+
+// ============================================================================
+// Record API Response Schemas
+// ============================================================================
+
+/**
+ * List records response schema
+ */
+export const listRecordsResponseSchema = z.object({
+  records: z.array(recordSchema).describe('List of records'),
+  pagination: paginationSchema.optional().describe('Pagination metadata'),
+  aggregations: z
+    .object({
+      count: z.string().optional().describe('Total count of records'),
+      sum: z.record(z.string(), z.number()).optional().describe('Sum aggregations by field'),
+      avg: z.record(z.string(), z.number()).optional().describe('Average aggregations by field'),
+      min: z.record(z.string(), z.number()).optional().describe('Minimum aggregations by field'),
+      max: z.record(z.string(), z.number()).optional().describe('Maximum aggregations by field'),
+    })
+    .optional()
+    .describe('Aggregation results'),
+})
+
+/**
+ * Get record response schema
+ *
+ * Returns record in flattened format (id, fields, timestamps, authorship at root level)
+ * to match test expectations and provide consistent API response structure.
+ */
+export const getRecordResponseSchema = z
+  .object({
+    id: z.union([z.string(), z.number()]).describe('Record identifier'),
+    fields: z
+      .record(z.string(), formattedFieldValueSchema)
+      .describe('User-defined field values (may include display formatting)'),
+    createdBy: z.string().optional().describe('User who created the record'),
+    updatedBy: z.string().optional().describe('User who last updated the record'),
+    deletedBy: userRefSchema.optional().describe('User who deleted the record'),
+  })
+  .extend(timestampSchema.shape)
+
+/**
+ * Create record response schema
+ *
+ * Returns record in flattened format (id, fields, timestamps at root level)
+ * to match test expectations and provide consistent API response structure.
+ */
+export const createRecordResponseSchema = z
+  .object({
+    id: z.string().describe('Record identifier'),
+    fields: z.record(z.string(), fieldValueSchema).describe('User-defined field values'),
+    createdBy: z.string().optional().describe('User who created the record'),
+    updatedBy: z.string().optional().describe('User who last updated the record'),
+  })
+  .extend(timestampSchema.shape)
+
+/**
+ * Update record response schema
+ */
+export const updateRecordResponseSchema = z.object({
+  record: recordSchema.describe('Updated record'),
+})
+
+/**
+ * Delete record response schema
+ */
+export const deleteRecordResponseSchema = z.object({
+  success: z.literal(true).describe('Record deleted'),
+})
+
+/**
+ * Restore record response schema
+ */
+export const restoreRecordResponseSchema = z.object({
+  success: z.literal(true).describe('Record restored'),
+  record: recordSchema.describe('Restored record'),
+})
+
+// ============================================================================
+// Batch Operation Schemas
+// ============================================================================
+
+/**
+ * Batch create records response schema
+ */
+export const batchCreateRecordsResponseSchema = z.object({
+  created: z.number().describe('Number of records created'),
+  records: z
+    .array(recordSchema)
+    .optional()
+    .describe('Created records (only if returnRecords=true)'),
+})
+
+/**
+ * Batch update records response schema
+ */
+export const batchUpdateRecordsResponseSchema = z.object({
+  updated: z.number().describe('Number of records updated'),
+  records: z
+    .array(recordSchema)
+    .optional()
+    .describe('Updated records (only if returnRecords=true)'),
+})
+
+/**
+ * Batch delete records response schema
+ */
+export const batchDeleteRecordsResponseSchema = z.object({
+  deleted: z.number().describe('Number of records deleted'),
+})
+
+/**
+ * Batch restore records response schema
+ */
+export const batchRestoreRecordsResponseSchema = z.object({
+  success: z.literal(true).describe('Batch restore succeeded'),
+  restored: z.number().describe('Number of records restored'),
+})
+
+/**
+ * Upsert records response schema
+ */
+export const upsertRecordsResponseSchema = z.object({
+  records: z.array(recordSchema).describe('Upserted records'),
+  created: z.number().describe('Number of records created'),
+  updated: z.number().describe('Number of records updated'),
+})
+
+// ============================================================================
+// View Schemas
+// ============================================================================
+
+/**
+ * View schema
+ */
+export const viewSchema = z
+  .object({
+    id: z.string().describe('View identifier'),
+    name: z.string().describe('View name'),
+    tableId: z.string().describe('Parent table ID'),
+    fields: z.array(z.string()).optional().describe('Visible field IDs'),
+    filters: z.array(z.unknown()).optional().describe('View filters'),
+    sorts: z.array(z.unknown()).optional().describe('View sorts'),
+    groupBy: z.string().optional().describe('Group by field'),
+  })
+  .extend(timestampSchema.shape)
+
+/**
+ * List views response schema
+ */
+export const listViewsResponseSchema = z.object({
+  views: z.array(viewSchema).describe('List of views'),
+})
+
+/**
+ * Get view response schema
+ * Returns view properties directly at root level
+ */
+export const getViewResponseSchema = z.object({
+  id: z.string().describe('View identifier'),
+  name: z.string().describe('View name'),
+  filters: z
+    .object({
+      and: z
+        .array(
+          z.object({
+            field: z.string(),
+            operator: z.string(),
+            value: z.unknown(),
+          })
+        )
+        .optional(),
+      or: z
+        .array(
+          z.object({
+            field: z.string(),
+            operator: z.string(),
+            value: z.unknown(),
+          })
+        )
+        .optional(),
+    })
+    .optional()
+    .describe('View filters'),
+  sorts: z
+    .array(
+      z.object({
+        field: z.string(),
+        direction: z.enum(['asc', 'desc']),
+      })
+    )
+    .optional()
+    .describe('View sorts'),
+  fields: z.array(z.string()).optional().describe('Visible field names'),
+  groupBy: z
+    .object({
+      field: z.string(),
+      direction: z.enum(['asc', 'desc']).optional(),
+    })
+    .optional()
+    .describe('Group by configuration'),
+  isDefault: z.boolean().optional().describe('Whether this is the default view'),
+})
+
+/**
+ * Get view records response schema
+ */
+export const getViewRecordsResponseSchema = z.object({
+  records: z.array(recordSchema).describe('Records matching view'),
+  pagination: paginationSchema.optional().describe('Pagination metadata'),
+})
+
+// ============================================================================
+// Permission Schemas
+// ============================================================================
+
+/**
+ * Table permission schema
+ */
+export const tablePermissionSchema = z.object({
+  read: z.boolean().describe('Can read records'),
+  create: z.boolean().describe('Can create records'),
+  update: z.boolean().describe('Can update records'),
+  delete: z.boolean().describe('Can delete records'),
+  manage: z.boolean().describe('Can manage table schema'),
+})
+
+/**
+ * Field permission schema
+ */
+export const fieldPermissionSchema = z.object({
+  read: z.boolean().describe('Can read field'),
+  write: z.boolean().describe('Can write field'),
+})
+
+/**
+ * Get table permissions response schema
+ */
+export const getTablePermissionsResponseSchema = z.object({
+  table: z
+    .object({
+      read: z.boolean().describe('Can read records'),
+      create: z.boolean().describe('Can create records'),
+      update: z.boolean().describe('Can update records'),
+      delete: z.boolean().describe('Can delete records'),
+    })
+    .describe('Table-level permissions'),
+  fields: z.record(z.string(), fieldPermissionSchema).describe('Field-level permissions'),
+})
+
+// ============================================================================
+// TypeScript Types
+// ============================================================================
+
+export type BaseField = z.infer<typeof baseFieldSchema>
+export type FieldValue = z.infer<typeof fieldValueSchema>
+export type Table = z.infer<typeof tableSchema>
+export type TableSummary = z.infer<typeof tableSummarySchema>
+export type Record = z.infer<typeof recordSchema>
+export type View = z.infer<typeof viewSchema>
+export type TablePermission = z.infer<typeof tablePermissionSchema>
+export type ListTablesResponse = z.infer<typeof listTablesResponseSchema>
+export type GetTableResponse = z.infer<typeof getTableResponseSchema>
+export type ListRecordsResponse = z.infer<typeof listRecordsResponseSchema>
+export type GetRecordResponse = z.infer<typeof getRecordResponseSchema>
+export type RestoreRecordResponse = z.infer<typeof restoreRecordResponseSchema>
+export type BatchRestoreRecordsResponse = z.infer<typeof batchRestoreRecordsResponseSchema>

package/src/domain/models/app/analytics/index.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Built-in Analytics Configuration Schema
+ *
+ * Configures the first-party, privacy-friendly analytics engine.
+ * When this property exists in the app config, analytics is enabled.
+ * When omitted, no analytics endpoints are available.
+ *
+ * Configuration forms:
+ * - `true` — Enable analytics with all defaults
+ * - `false` — Explicitly disable analytics
+ * - `{ ... }` — Enable analytics with custom options
+ *
+ * Design principles:
+ * - No cookies (visitor hashing via SHA-256)
+ * - No external dependencies
+ * - GDPR-friendly by default (respectDoNotTrack: true)
+ * - Configurable data retention
+ *
+ * @example
+ * ```typescript
+ * // Enable with all defaults
+ * true
+ *
+ * // Explicitly disabled
+ * false
+ *
+ * // Custom retention and excluded paths
+ * {
+ *   retentionDays: 90,
+ *   excludedPaths: ['/admin/*', '/api/*'],
+ *   sessionTimeout: 15
+ * }
+ * ```
+ */
+export const BuiltInAnalyticsSchema = Schema.Union(
+  Schema.Boolean,
+  Schema.Struct({
+    /**
+     * Number of days to retain analytics data (optional).
+     *
+     * Must be between 1 and 730 days (2 years).
+     * Defaults to 365 days. Data older than this is automatically purged.
+     */
+    retentionDays: Schema.optional(
+      Schema.Number.pipe(
+        Schema.int(),
+        Schema.between(1, 730),
+        Schema.annotations({
+          title: 'Retention Days',
+          description: 'Number of days to retain analytics data (1-730)',
+        })
+      )
+    ),
+
+    /**
+     * URL path patterns to exclude from tracking (optional).
+     *
+     * Glob patterns matching page paths that should not be tracked.
+     * Useful for excluding admin pages, API docs, or internal routes.
+     */
+    excludedPaths: Schema.optional(
+      Schema.Array(Schema.String).pipe(
+        Schema.annotations({
+          title: 'Excluded Paths',
+          description: 'Glob patterns for paths excluded from tracking',
+        })
+      )
+    ),
+
+    /**
+     * Whether to honor the Do Not Track browser setting (optional).
+     *
+     * When true, visitors with DNT:1 header will not be tracked.
+     * Defaults to true for privacy compliance.
+     */
+    respectDoNotTrack: Schema.optional(Schema.Boolean),
+
+    /**
+     * Session timeout in minutes (optional).
+     *
+     * Time of inactivity before a new session is created.
+     * Must be between 1 and 120 minutes. Defaults to 30 minutes.
+     */
+    sessionTimeout: Schema.optional(
+      Schema.Number.pipe(
+        Schema.int(),
+        Schema.between(1, 120),
+        Schema.annotations({
+          title: 'Session Timeout',
+          description: 'Session timeout in minutes (1-120)',
+        })
+      )
+    ),
+  })
+).pipe(
+  Schema.annotations({
+    title: 'Built-in Analytics Configuration',
+    description:
+      'First-party, privacy-friendly analytics engine. No cookies, no external dependencies, GDPR-compliant.',
+    examples: [
+      true,
+      {
+        retentionDays: 90,
+        excludedPaths: ['/admin/*', '/api/*'],
+        sessionTimeout: 15,
+      },
+      false,
+    ],
+  })
+)
+
+/**
+ * TypeScript type inferred from BuiltInAnalyticsSchema
+ */
+export type BuiltInAnalytics = Schema.Schema.Type<typeof BuiltInAnalyticsSchema>
+
+/**
+ * Encoded type of BuiltInAnalyticsSchema (what goes in before validation)
+ */
+export type BuiltInAnalyticsEncoded = Schema.Schema.Encoded<typeof BuiltInAnalyticsSchema>

package/src/domain/models/app/auth/config.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Auth Email Template Schema
+ *
+ * Configuration for a single authentication email template.
+ * Templates support variable substitution using $variable syntax.
+ *
+ * Available variables depend on the email type:
+ * - $url: Link URL (verification, password reset, magic link)
+ * - $name: User's name
+ * - $email: User's email address
+ * - $code: OTP code (for email-otp)
+ * - $organizationName: Organization name (for invitations)
+ * - $inviterName: Name of person who sent invitation
+ *
+ * @example
+ * ```typescript
+ * {
+ *   subject: 'Reset your password',
+ *   text: 'Click the link to reset your password: $url'
+ * }
+ * ```
+ */
+export const AuthEmailTemplateSchema = Schema.Struct({
+  /** Email subject line (can include $variables) */
+  subject: Schema.String.pipe(
+    Schema.annotations({ description: 'Email subject line with optional $variable substitution' })
+  ),
+  /** Plain text email body (can include $variables) */
+  text: Schema.optional(
+    Schema.String.pipe(
+      Schema.annotations({
+        description: 'Plain text email body with optional $variable substitution',
+      })
+    )
+  ),
+  /** HTML email body (can include $variables) */
+  html: Schema.optional(
+    Schema.String.pipe(
+      Schema.annotations({ description: 'HTML email body with optional $variable substitution' })
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Auth Email Template',
+    description: 'Email template configuration with subject and body content',
+    examples: [
+      { subject: 'Verify your email', text: 'Click here to verify: $url' },
+      {
+        subject: 'Reset your password',
+        text: 'Click the link to reset your password: $url',
+        html: '<p>Click <a href="$url">here</a> to reset your password.</p>',
+      },
+    ],
+  })
+)
+
+export type AuthEmailTemplate = Schema.Schema.Type<typeof AuthEmailTemplateSchema>
+
+/**
+ * Auth Email Templates Schema
+ *
+ * All available email templates for authentication flows.
+ * Each template is optional - Better Auth provides sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   verification: {
+ *     subject: 'Verify your email for MyApp',
+ *     text: 'Hi $name, click here to verify your email: $url'
+ *   },
+ *   resetPassword: {
+ *     subject: 'Reset your password',
+ *     text: 'Click the link to reset your password: $url'
+ *   }
+ * }
+ * ```
+ */
+export const AuthEmailTemplatesSchema = Schema.Struct({
+  /** Email verification after signup */
+  verification: Schema.optional(AuthEmailTemplateSchema),
+  /** Password reset email */
+  resetPassword: Schema.optional(AuthEmailTemplateSchema),
+  /** Magic link login email */
+  magicLink: Schema.optional(AuthEmailTemplateSchema),
+  /** Email OTP code email */
+  emailOtp: Schema.optional(AuthEmailTemplateSchema),
+  /** Two-factor authentication backup codes email */
+  twoFactorBackupCodes: Schema.optional(AuthEmailTemplateSchema),
+  /** Welcome email after verification */
+  welcome: Schema.optional(AuthEmailTemplateSchema),
+  /** Account deletion confirmation email */
+  accountDeletion: Schema.optional(AuthEmailTemplateSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'Auth Email Templates',
+    description: 'Templates for all authentication-related emails',
+    examples: [
+      {
+        verification: { subject: 'Verify your email', text: 'Click to verify: $url' },
+        resetPassword: { subject: 'Reset your password', text: 'Reset link: $url' },
+      },
+    ],
+  })
+)
+
+export type AuthEmailTemplates = Schema.Schema.Type<typeof AuthEmailTemplatesSchema>