@elevasis/core 0.1.0

package/src/operations/notifications/__tests__/api-schemas.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest'
+import {
+  GetNotificationsQuerySchema,
+  MarkAsReadParamsSchema,
+  CreateNotificationSchema,
+  NotificationCategorySchema
+} from '../api-schemas'
+
+describe('GetNotificationsQuerySchema', () => {
+  it('accepts valid limit', () => {
+    const result = GetNotificationsQuerySchema.safeParse({ limit: '50' })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.limit).toBe(50) // Coerced to number
+    }
+  })
+
+  it('applies default limit', () => {
+    const result = GetNotificationsQuerySchema.safeParse({})
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.limit).toBe(50)
+    }
+  })
+
+  it('rejects limit > 100 (DoS prevention)', () => {
+    const result = GetNotificationsQuerySchema.safeParse({ limit: '101' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects limit < 1', () => {
+    const result = GetNotificationsQuerySchema.safeParse({ limit: '0' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects non-numeric limit', () => {
+    const result = GetNotificationsQuerySchema.safeParse({ limit: 'abc' })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts numeric limit', () => {
+    const result = GetNotificationsQuerySchema.safeParse({ limit: 25 })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.limit).toBe(25)
+    }
+  })
+})
+
+describe('MarkAsReadParamsSchema', () => {
+  it('accepts valid UUID', () => {
+    const result = MarkAsReadParamsSchema.safeParse({
+      id: '123e4567-e89b-12d3-a456-426614174000'
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects non-UUID string', () => {
+    const result = MarkAsReadParamsSchema.safeParse({ id: 'not-a-uuid' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty string', () => {
+    const result = MarkAsReadParamsSchema.safeParse({ id: '' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects SQL injection attempt', () => {
+    const result = MarkAsReadParamsSchema.safeParse({ id: "'; DROP TABLE notifications;--" })
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('CreateNotificationSchema', () => {
+  const validNotification = {
+    userId: '123e4567-e89b-12d3-a456-426614174000',
+    organizationId: '123e4567-e89b-12d3-a456-426614174001',
+    category: 'info' as const,
+    title: 'Test Notification',
+    message: 'This is a test message'
+  }
+
+  it('accepts valid notification', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      actionUrl: 'https://example.com/action'
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts notification without actionUrl', () => {
+    const result = CreateNotificationSchema.safeParse(validNotification)
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects invalid category', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      category: 'invalid'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects title too long (DoS prevention)', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      title: 'a'.repeat(201)
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects message too long (DoS prevention)', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      message: 'a'.repeat(1001)
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts title at max length', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      title: 'a'.repeat(200)
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts message at max length', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      message: 'a'.repeat(1000)
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects invalid actionUrl', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      actionUrl: 'not-a-url'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid userId UUID', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      userId: 'not-a-uuid'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid organizationId UUID', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      organizationId: 'not-a-uuid'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('trims whitespace from title and message', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      title: '  Test  ',
+      message: '  Message  '
+    })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.title).toBe('Test')
+      expect(result.data.message).toBe('Message')
+    }
+  })
+
+  it('rejects empty title after trim', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      title: '   '
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty message after trim', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      message: '   '
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('prevents unknown fields (strict mode - mass assignment prevention)', () => {
+    const result = CreateNotificationSchema.safeParse({
+      ...validNotification,
+      unknownField: 'should fail'
+    })
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('NotificationCategorySchema', () => {
+  it('accepts all valid categories', () => {
+    const categories = ['info', 'queue', 'alert', 'error', 'system']
+    categories.forEach((category) => {
+      const result = NotificationCategorySchema.safeParse(category)
+      expect(result.success).toBe(true)
+    })
+  })
+
+  it('rejects invalid category', () => {
+    const result = NotificationCategorySchema.safeParse('invalid')
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty string', () => {
+    const result = NotificationCategorySchema.safeParse('')
+    expect(result.success).toBe(false)
+  })
+})

package/src/operations/notifications/api-schemas.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod'
+import { UuidSchema } from '../../platform/utils/validation'
+
+/**
+ * API validation schemas for notification endpoints.
+ * Separate from domain types to enforce input validation at API boundary.
+ */
+
+/**
+ * Notification category enum (matches database constraint)
+ */
+export const NotificationCategorySchema = z.enum(['info', 'queue', 'alert', 'error', 'system'])
+
+/**
+ * GET /api/notifications - Query parameters
+ *
+ * Security:
+ * - limit: Max 100 to prevent DoS via excessive data transfer
+ * - Default: 50 notifications
+ * - Coerced from string to number (query params are always strings)
+ */
+export const GetNotificationsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  offset: z.coerce.number().int().min(0).default(0)
+})
+
+/**
+ * PATCH /api/notifications/:id/read - Path parameters
+ *
+ * Security:
+ * - UUID validation prevents SQL injection attempts
+ */
+export const MarkAsReadParamsSchema = z.object({
+  id: UuidSchema
+})
+
+/**
+ * Internal: Create notification schema
+ * Used by notification service/triggers, not exposed as API endpoint
+ * (notifications are created by system only, not by users)
+ *
+ * Security:
+ * - Strict mode: prevents mass assignment attacks
+ * - UUID validation: ensures valid user/org IDs
+ * - Length limits: prevents DoS via large payloads
+ *   - Title: 200 chars (reasonable for notification headers)
+ *   - Message: 1000 chars (detailed messages without DoS risk)
+ * - URL validation: ensures actionUrl is valid URL if provided
+ */
+export const CreateNotificationSchema = z
+  .object({
+    userId: UuidSchema,
+    organizationId: UuidSchema,
+    category: NotificationCategorySchema,
+    title: z.string().trim().min(1).max(200),
+    message: z.string().trim().min(1).max(1000),
+    actionUrl: z.string().url().optional()
+  })
+  .strict()
+
+/**
+ * PATCH /api/notifications/batch/read - Request body
+ *
+ * Security:
+ * - Strict mode: prevents mass assignment attacks
+ * - UUID array validation: ensures valid notification IDs
+ * - Min 1 / Max 500: prevents empty no-op calls and oversized batches
+ */
+export const BatchMarkAsReadRequestSchema = z
+  .object({
+    ids: z.array(UuidSchema).min(1).max(500)
+  })
+  .strict()
+
+/**
+ * Bundled export (mirrors ProjectSchemas pattern)
+ */
+export const NotificationSchemas = {
+  GetNotificationsQuery: GetNotificationsQuerySchema,
+  MarkAsReadParams: MarkAsReadParamsSchema,
+  CreateNotification: CreateNotificationSchema,
+  BatchMarkAsReadRequest: BatchMarkAsReadRequestSchema
+}
+
+/**
+ * Type exports for use in handlers
+ */
+export type GetNotificationsQuery = z.infer<typeof GetNotificationsQuerySchema>
+export type MarkAsReadParams = z.infer<typeof MarkAsReadParamsSchema>
+export type CreateNotificationInput = z.infer<typeof CreateNotificationSchema>
+export type BatchMarkAsReadRequest = z.infer<typeof BatchMarkAsReadRequestSchema>

package/src/operations/notifications/index.ts

@@ -0,0 +1,3 @@
+export * from './types'
+export * from './api-schemas'
+export * from './sse-events'

package/src/operations/notifications/sse-events.ts

@@ -0,0 +1,21 @@
+/**
+ * Notification SSE Event Types
+ *
+ * Type-safe definitions for notification-related SSE events
+ */
+
+/**
+ * Event sent when notification unread count changes
+ */
+export interface NotificationCountUpdatedEvent {
+  type: 'unread_count_updated'
+  timestamp: number
+  data: {
+    count: number
+  }
+}
+
+/**
+ * Union of all notification SSE events
+ */
+export type NotificationSSEEvent = NotificationCountUpdatedEvent

package/src/operations/notifications/types.ts

@@ -0,0 +1,47 @@
+import type { Database } from '../../supabase/database.types'
+
+// Import Supabase-generated types (don't recreate!)
+export type NotificationRow = Database['public']['Tables']['notifications']['Row']
+export type NotificationInsert = Database['public']['Tables']['notifications']['Insert']
+export type NotificationUpdate = Database['public']['Tables']['notifications']['Update']
+
+// Only create types for business logic transformations
+export interface Notification {
+  id: string
+  userId: string // Transformed from user_id
+  organizationId: string // Transformed from organization_id
+  category: NotificationRow['category']
+  title: string
+  message: string
+  actionUrl: string | null // Transformed from action_url
+  read: boolean
+  readAt: Date | null // Transformed from read_at
+  createdAt: Date // Transformed from created_at
+}
+
+export interface CreateNotificationParams {
+  userId: string
+  organizationId: string
+  category: NotificationRow['category']
+  title: string
+  message: string
+  actionUrl?: string
+}
+
+/**
+ * Wire-format DTO for notification API responses.
+ * Dates are ISO 8601 strings (not Date objects like the domain Notification type).
+ * Used by frontend hooks that consume /api/notifications.
+ */
+export interface NotificationDTO {
+  id: string
+  userId: string
+  organizationId: string
+  category: string
+  title: string
+  message: string
+  actionUrl: string | null
+  read: boolean
+  readAt: string | null
+  createdAt: string
+}

package/src/operations/observability/__tests__/openrouter-cost-flow.test.ts

@@ -0,0 +1,297 @@
+/**
+ * OpenRouter Cost Flow Integration Tests
+ * Verifies that actual cost from OpenRouter flows through the full observability pipeline:
+ * OpenRouterAdapter → UniversalLLMAdapter → AIUsageCollector → Database
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { AIUsageCollector } from '../ai-usage-collector'
+import { UniversalLLMAdapter } from '../../../execution/engine/llm/adapters/universal-adapter'
+import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../../../execution/engine/llm/types'
+import type { LLMModel } from '../../../execution/engine/llm/model-info'
+
+describe('OpenRouter Cost Flow', () => {
+  describe('AIUsageCollector', () => {
+    it('uses actual cost when provided by adapter', () => {
+      const collector = new AIUsageCollector()
+
+      collector.record({
+        model: 'openrouter/anthropic/claude-sonnet-4.5',
+        inputTokens: 100,
+        outputTokens: 50,
+        latencyMs: 1500,
+        cost: 0.00125 // Actual cost from OpenRouter
+      })
+
+      const summary = collector.getSummary()
+
+      expect(summary.totalCostUsd).toBe(0.00125)
+      expect(summary.calls[0].costUsd).toBe(0.00125)
+    })
+
+    it('falls back to calculateCost when cost not provided', () => {
+      const collector = new AIUsageCollector()
+
+      collector.record({
+        model: 'gpt-5-mini',
+        inputTokens: 100,
+        outputTokens: 50,
+        latencyMs: 1000
+        // No cost field - should use calculateCost()
+      })
+
+      const summary = collector.getSummary()
+
+      // Should have calculated a cost (not zero, not undefined)
+      expect(summary.totalCostUsd).toBeGreaterThan(0)
+      expect(summary.calls[0].costUsd).toBeGreaterThan(0)
+    })
+
+    it('handles mixed providers - some with actual cost, some calculated', () => {
+      const collector = new AIUsageCollector()
+
+      // OpenRouter call with actual cost
+      collector.record({
+        model: 'openrouter/anthropic/claude-sonnet-4.5',
+        inputTokens: 100,
+        outputTokens: 50,
+        latencyMs: 1500,
+        cost: 0.00125
+      })
+
+      // OpenAI call without cost (will be calculated)
+      collector.record({
+        model: 'gpt-5-mini',
+        inputTokens: 200,
+        outputTokens: 100,
+        latencyMs: 800
+      })
+
+      const summary = collector.getSummary()
+
+      expect(summary.callCount).toBe(2)
+      expect(summary.calls[0].costUsd).toBe(0.00125) // Actual
+      expect(summary.calls[1].costUsd).toBeGreaterThan(0) // Calculated
+      expect(summary.totalCostUsd).toBeGreaterThan(0.00125) // Sum of both
+    })
+
+    it('uses actual cost of zero when explicitly provided', () => {
+      const collector = new AIUsageCollector()
+
+      // Edge case: OpenRouter returns cost of 0 (e.g., free tier, cached response)
+      collector.record({
+        model: 'openrouter/anthropic/claude-sonnet-4.5',
+        inputTokens: 100,
+        outputTokens: 50,
+        latencyMs: 500,
+        cost: 0 // Explicitly zero (not undefined)
+      })
+
+      const summary = collector.getSummary()
+
+      // Should use the explicit zero, not fall back to calculated cost
+      expect(summary.totalCostUsd).toBe(0)
+      expect(summary.calls[0].costUsd).toBe(0)
+    })
+  })
+
+  describe('UniversalLLMAdapter Cost Passthrough', () => {
+    let mockBaseAdapter: LLMAdapter
+    let collector: AIUsageCollector
+
+    const baseRequest: LLMGenerateRequest = {
+      messages: [{ role: 'user', content: 'Hello' }],
+      responseSchema: { type: 'object', properties: { response: { type: 'string' } } },
+      maxOutputTokens: 1000
+    }
+
+    beforeEach(() => {
+      vi.clearAllMocks()
+      collector = new AIUsageCollector()
+    })
+
+    it('passes actual cost from response to collector', async () => {
+      // Mock adapter that returns response with cost (like OpenRouter)
+      mockBaseAdapter = {
+        generate: vi.fn().mockResolvedValue({
+          output: { response: 'Hello!' },
+          usage: {
+            inputTokens: 15,
+            outputTokens: 25,
+            totalTokens: 40
+          },
+          cost: 0.00089 // Actual cost from OpenRouter
+        } as LLMGenerateResponse)
+      }
+
+      const universalAdapter = new UniversalLLMAdapter(
+        mockBaseAdapter,
+        'openrouter/anthropic/claude-sonnet-4.5' as LLMModel,
+        collector,
+        'agent-reasoning'
+      )
+
+      await universalAdapter.generate(baseRequest)
+
+      const summary = collector.getSummary()
+
+      expect(summary.callCount).toBe(1)
+      expect(summary.calls[0].costUsd).toBe(0.00089)
+      expect(summary.totalCostUsd).toBe(0.00089)
+    })
+
+    it('collector calculates cost when response has no cost field', async () => {
+      // Mock adapter that returns response without cost (like OpenAI)
+      mockBaseAdapter = {
+        generate: vi.fn().mockResolvedValue({
+          output: { response: 'Hello!' },
+          usage: {
+            inputTokens: 15,
+            outputTokens: 25,
+            totalTokens: 40
+          }
+          // No cost field
+        } as LLMGenerateResponse)
+      }
+
+      const universalAdapter = new UniversalLLMAdapter(
+        mockBaseAdapter,
+        'gpt-5-mini' as LLMModel,
+        collector,
+        'agent-reasoning'
+      )
+
+      await universalAdapter.generate(baseRequest)
+
+      const summary = collector.getSummary()
+
+      expect(summary.callCount).toBe(1)
+      // Cost should be calculated (not zero, not undefined)
+      expect(summary.calls[0].costUsd).toBeGreaterThan(0)
+    })
+
+    it('tracks multiple calls with mixed cost sources', async () => {
+      // First call: OpenRouter with actual cost
+      const openRouterAdapter: LLMAdapter = {
+        generate: vi.fn().mockResolvedValue({
+          output: { response: 'Hello from Claude!' },
+          usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+          cost: 0.0025
+        } as LLMGenerateResponse)
+      }
+
+      // Second call: OpenAI without cost
+      const openAIAdapter: LLMAdapter = {
+        generate: vi.fn().mockResolvedValue({
+          output: { response: 'Hello from GPT!' },
+          usage: { inputTokens: 80, outputTokens: 40, totalTokens: 120 }
+        } as LLMGenerateResponse)
+      }
+
+      const universalOpenRouter = new UniversalLLMAdapter(
+        openRouterAdapter,
+        'openrouter/anthropic/claude-sonnet-4.5' as LLMModel,
+        collector,
+        'agent-reasoning'
+      )
+
+      const universalOpenAI = new UniversalLLMAdapter(
+        openAIAdapter,
+        'gpt-5-mini' as LLMModel,
+        collector,
+        'workflow-step'
+      )
+
+      await universalOpenRouter.generate(baseRequest)
+      await universalOpenAI.generate(baseRequest)
+
+      const summary = collector.getSummary()
+
+      expect(summary.callCount).toBe(2)
+      expect(summary.calls[0].costUsd).toBe(0.0025) // Actual from OpenRouter
+      expect(summary.calls[1].costUsd).toBeGreaterThan(0) // Calculated for OpenAI
+      expect(summary.totalCostUsd).toBeGreaterThan(0.0025) // Sum
+    })
+
+    it('preserves call context alongside cost', async () => {
+      mockBaseAdapter = {
+        generate: vi.fn().mockResolvedValue({
+          output: { response: 'Hello!' },
+          usage: { inputTokens: 50, outputTokens: 25, totalTokens: 75 },
+          cost: 0.00045
+        } as LLMGenerateResponse)
+      }
+
+      const universalAdapter = new UniversalLLMAdapter(
+        mockBaseAdapter,
+        'openrouter/deepseek/deepseek-v3.2' as LLMModel,
+        collector,
+        'agent-reasoning',
+        { type: 'agent-reasoning', iteration: 3 }
+      )
+
+      await universalAdapter.generate(baseRequest)
+
+      const summary = collector.getSummary()
+      const call = summary.calls[0]
+
+      // Verify cost is captured
+      expect(call.costUsd).toBe(0.00045)
+
+      // Verify context is preserved
+      expect(call.callType).toBe('agent-reasoning')
+      expect(call.context).toEqual({ type: 'agent-reasoning', iteration: 3 })
+
+      // Verify tokens are tracked
+      expect(call.inputTokens).toBe(50)
+      expect(call.outputTokens).toBe(25)
+    })
+  })
+
+  describe('End-to-End Cost Accuracy', () => {
+    it('aggregates costs correctly across multiple calls', () => {
+      const collector = new AIUsageCollector()
+
+      // Simulate a typical execution with multiple LLM calls
+      const calls = [
+        { model: 'openrouter/anthropic/claude-sonnet-4.5', cost: 0.00125 },
+        { model: 'openrouter/anthropic/claude-sonnet-4.5', cost: 0.00089 },
+        { model: 'openrouter/deepseek/deepseek-v3.2', cost: 0.00034 }
+      ]
+
+      calls.forEach((call, i) => {
+        collector.record({
+          model: call.model as LLMModel,
+          inputTokens: 100 + i * 50,
+          outputTokens: 50 + i * 25,
+          latencyMs: 1000 + i * 200,
+          cost: call.cost
+        })
+      })
+
+      const summary = collector.getSummary()
+
+      expect(summary.callCount).toBe(3)
+      expect(summary.totalCostUsd).toBe(0.00125 + 0.00089 + 0.00034)
+      expect(summary.totalCostUsd).toBeCloseTo(0.00248, 5)
+    })
+
+    it('maintains precision for small costs', () => {
+      const collector = new AIUsageCollector()
+
+      // Very small cost (e.g., DeepSeek which is very cheap)
+      collector.record({
+        model: 'openrouter/deepseek/deepseek-v3.2',
+        inputTokens: 10,
+        outputTokens: 5,
+        latencyMs: 200,
+        cost: 0.000001 // $0.000001 = $1 per million tokens
+      })
+
+      const summary = collector.getSummary()
+
+      expect(summary.totalCostUsd).toBe(0.000001)
+      expect(summary.calls[0].costUsd).toBe(0.000001)
+    })
+  })
+})