@elevasis/core 0.1.0

package/src/platform/utils/currency.ts

@@ -0,0 +1,96 @@
+/**
+ * Currency formatting utilities
+ *
+ * These utilities handle formatting of USD currency values for display.
+ * Database stores values as NUMERIC (exact decimal precision), JavaScript
+ * uses number (IEEE 754 floating point).
+ */
+
+/**
+ * Format USD amount for display
+ *
+ * @param amountUsd - Amount in USD (e.g., 1.375 = $1.38)
+ * @param options - Formatting options
+ * @returns Formatted string (e.g., "$1.38")
+ *
+ * @example
+ * formatCurrency(1.375) // "$1.38"
+ * formatCurrency(0.001) // "$0.00"
+ * formatCurrency(1234.56) // "$1,234.56"
+ * formatCurrency(1.5, { minimumFractionDigits: 4 }) // "$1.5000"
+ */
+export function formatCurrency(
+  amountUsd: number,
+  options: {
+    minimumFractionDigits?: number
+    maximumFractionDigits?: number
+  } = {}
+): string {
+  const {
+    minimumFractionDigits = 2,
+    maximumFractionDigits = 2
+  } = options
+
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits,
+    maximumFractionDigits
+  }).format(amountUsd)
+}
+
+/**
+ * Format USD amount with high precision (for debugging/technical displays)
+ *
+ * @param amountUsd - Amount in USD
+ * @returns Formatted string with 6 decimal places (e.g., "$0.001375")
+ *
+ * @example
+ * formatCurrencyPrecise(0.001375) // "$0.001375"
+ * formatCurrencyPrecise(1.5) // "$1.500000"
+ */
+export function formatCurrencyPrecise(amountUsd: number): string {
+  return formatCurrency(amountUsd, {
+    minimumFractionDigits: 6,
+    maximumFractionDigits: 6
+  })
+}
+
+/**
+ * Format USD amount as compact notation (for charts/dashboards)
+ *
+ * @param amountUsd - Amount in USD
+ * @returns Compact formatted string (e.g., "$1.2K", "$3.5M")
+ *
+ * @example
+ * formatCurrencyCompact(1234) // "$1.2K"
+ * formatCurrencyCompact(1500000) // "$1.5M"
+ * formatCurrencyCompact(5) // "$5"
+ */
+export function formatCurrencyCompact(amountUsd: number): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    notation: 'compact',
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 1
+  }).format(amountUsd)
+}
+
+/**
+ * Parse string USD amount to number (for form inputs)
+ *
+ * @param value - String value (e.g., "$1,234.56" or "1234.56")
+ * @returns Parsed number or null if invalid
+ *
+ * @example
+ * parseCurrency("$1,234.56") // 1234.56
+ * parseCurrency("1234.56") // 1234.56
+ * parseCurrency("invalid") // null
+ */
+export function parseCurrency(value: string): number | null {
+  // Remove currency symbol and commas
+  const cleaned = value.replace(/[$,]/g, '').trim()
+  const parsed = parseFloat(cleaned)
+  return isNaN(parsed) ? null : parsed
+}

package/src/platform/utils/debounce.ts

@@ -0,0 +1,52 @@
+/**
+ * Debounce utility for delaying function execution
+ *
+ * Creates a debounced version of a function that delays invoking until
+ * after `wait` milliseconds have elapsed since the last time it was invoked.
+ */
+
+/**
+ * Creates a debounced function that delays invoking `fn` until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was invoked.
+ *
+ * @param fn - The function to debounce
+ * @param wait - The number of milliseconds to delay
+ * @returns A debounced version of the function with a `cancel` method
+ *
+ * @example
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('Searching for:', query)
+ * }, 300)
+ *
+ * debouncedSearch('a')
+ * debouncedSearch('ab')
+ * debouncedSearch('abc') // Only this one executes after 300ms
+ *
+ * // Cancel pending execution
+ * debouncedSearch.cancel()
+ */
+export function debounce<T extends (...args: Parameters<T>) => void>(
+  fn: T,
+  wait: number
+): ((...args: Parameters<T>) => void) & { cancel: () => void } {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+
+  const debounced = (...args: Parameters<T>) => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId)
+    }
+    timeoutId = setTimeout(() => {
+      fn(...args)
+      timeoutId = null
+    }, wait)
+  }
+
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId)
+      timeoutId = null
+    }
+  }
+
+  return debounced
+}

package/src/platform/utils/error.ts

@@ -0,0 +1,42 @@
+/**
+ * Error utility functions
+ */
+
+import { ZodError } from 'zod'
+
+/**
+ * Convert unknown error to string message
+ * Handles Error objects and other types safely
+ * Includes special handling for Zod validation errors
+ */
+export function errorToString(error: unknown): string {
+  if (error instanceof ZodError) {
+    // Format Zod validation errors with field path and details
+    return JSON.stringify(error.issues, null, 2)
+  }
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Extract structured error details for logging
+ * Includes validation errors, stack traces, and context
+ */
+export function getErrorDetails(error: unknown): Record<string, unknown> {
+  const details: Record<string, unknown> = {
+    message: errorToString(error),
+    type: error instanceof Error ? error.constructor.name : typeof error
+  }
+
+  // Add Zod validation details
+  if (error instanceof ZodError) {
+    details.validationErrors = error.issues
+    details.isValidationError = true
+  }
+
+  // Add stack trace for Error objects
+  if (error instanceof Error && error.stack) {
+    details.stack = error.stack
+  }
+
+  return details
+}

package/src/platform/utils/hmac.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { generateHmacToken, verifyHmacToken, generateBrochureUrl } from './server/hmac'
+
+describe('HMAC Token Utilities', () => {
+  const TEST_SECRET = 'test-secret-key-12345'
+  const TEST_CONTACT_ID = '550e8400-e29b-41d4-a716-446655440000'
+
+  describe('generateHmacToken', () => {
+    it('returns 16-character hex token', () => {
+      const token = generateHmacToken('test-data', TEST_SECRET)
+      expect(token).toHaveLength(16)
+      expect(token).toMatch(/^[0-9a-f]{16}$/)
+    })
+
+    it('produces consistent tokens for same input', () => {
+      const token1 = generateHmacToken('test@example.com', TEST_SECRET)
+      const token2 = generateHmacToken('test@example.com', TEST_SECRET)
+      expect(token1).toBe(token2)
+    })
+
+    it('normalizes input (lowercase and trim)', () => {
+      const token1 = generateHmacToken('TEST@EXAMPLE.COM', TEST_SECRET)
+      const token2 = generateHmacToken('  test@example.com  ', TEST_SECRET)
+      const token3 = generateHmacToken('test@example.com', TEST_SECRET)
+      expect(token1).toBe(token2)
+      expect(token2).toBe(token3)
+    })
+
+    it('produces different tokens for different secrets', () => {
+      const token1 = generateHmacToken('data', 'secret1')
+      const token2 = generateHmacToken('data', 'secret2')
+      expect(token1).not.toBe(token2)
+    })
+
+    it('produces different tokens for different data', () => {
+      const token1 = generateHmacToken('data1', TEST_SECRET)
+      const token2 = generateHmacToken('data2', TEST_SECRET)
+      expect(token1).not.toBe(token2)
+    })
+  })
+
+  describe('verifyHmacToken', () => {
+    it('returns true for valid token', () => {
+      const token = generateHmacToken(TEST_CONTACT_ID, TEST_SECRET)
+      const isValid = verifyHmacToken(TEST_CONTACT_ID, token, TEST_SECRET)
+      expect(isValid).toBe(true)
+    })
+
+    it('returns false for invalid token', () => {
+      const isValid = verifyHmacToken(TEST_CONTACT_ID, 'invalid-token-00', TEST_SECRET)
+      expect(isValid).toBe(false)
+    })
+
+    it('returns false for wrong length token', () => {
+      const isValid = verifyHmacToken(TEST_CONTACT_ID, 'short', TEST_SECRET)
+      expect(isValid).toBe(false)
+    })
+
+    it('returns false for wrong secret', () => {
+      const token = generateHmacToken(TEST_CONTACT_ID, TEST_SECRET)
+      const isValid = verifyHmacToken(TEST_CONTACT_ID, token, 'wrong-secret')
+      expect(isValid).toBe(false)
+    })
+
+    it('verifies with normalized input', () => {
+      const token = generateHmacToken('test@example.com', TEST_SECRET)
+      const isValid = verifyHmacToken('  TEST@EXAMPLE.COM  ', token, TEST_SECRET)
+      expect(isValid).toBe(true)
+    })
+  })
+
+  describe('generateBrochureUrl', () => {
+    it('generates URL with default base', () => {
+      const url = generateBrochureUrl(TEST_CONTACT_ID, TEST_SECRET)
+      expect(url).toMatch(/^https:\/\/brochure\.elevasis\.io\//)
+      expect(url).toContain(TEST_CONTACT_ID)
+      expect(url).toMatch(/\?t=[0-9a-f]{16}$/)
+    })
+
+    it('generates URL with custom base', () => {
+      const customBase = 'https://custom.example.com/brochure'
+      const url = generateBrochureUrl(TEST_CONTACT_ID, TEST_SECRET, customBase)
+      expect(url).toMatch(/^https:\/\/custom\.example\.com\/brochure\//)
+      expect(url).toContain(TEST_CONTACT_ID)
+    })
+
+    it('generates verifiable token in URL', () => {
+      const url = generateBrochureUrl(TEST_CONTACT_ID, TEST_SECRET)
+      const tokenMatch = url.match(/\?t=([0-9a-f]{16})$/)
+      expect(tokenMatch).not.toBeNull()
+
+      const extractedToken = tokenMatch![1]
+      const isValid = verifyHmacToken(TEST_CONTACT_ID, extractedToken, TEST_SECRET)
+      expect(isValid).toBe(true)
+    })
+  })
+})

package/src/platform/utils/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Core utility functions
+ */
+
+export { debounce } from './debounce'
+export { errorToString, getErrorDetails } from './error'
+export { formatCurrency, formatCurrencyPrecise, formatCurrencyCompact, parseCurrency } from './currency'
+export { estimateTokens, validateTokenLimit, TOKEN_LIMITS } from './token-counter'
+export type { TokenCountResult, TokenLimits } from './token-counter'
+export {
+  UuidSchema,
+  NonEmptyStringSchema,
+  EmailSchema,
+  UrlSchema,
+  PaginationSchema,
+  TimestampSchema,
+  DateRangeSchema,
+  ResourceTypeSchema,
+  OriginResourceTypeSchema,
+  CredentialNameSchema,
+  OrganizationIdSchema,
+  OAuthProviderSchema,
+  OAuthCodeSchema,
+  OAuthStateParamSchema,
+  SanitizedStringSchema,
+  createEnumSchema,
+  createStringSchema,
+  createArraySchema,
+  createPayloadSizeValidator,
+  formatZodValidationError
+} from './validation'
+export type { PaginationParams, DateRange, ValidationErrorResponse, PaginatedResponse } from './validation'

package/src/platform/utils/server/betterstack-logger.ts

@@ -0,0 +1,210 @@
+import { ExecutionError } from '../../../execution/engine/base/errors'
+
+/**
+ * Better Stack Logger (Simplified)
+ *
+ * Production-only error logging using Sentry SDK pointing to Better Stack.
+ * Provides domain-specific context that global error handler cannot infer.
+ *
+ * **Design Philosophy:**
+ * - Global error handler (setup-error-handler.ts) catches ALL errors automatically
+ * - bslog functions only add value when they provide context the global handler can't capture
+ * - WebSocket, SSE, Database, and Critical errors are already handled by global error handler
+ * - Only use these functions for external services and execution failures that need special context
+ *
+ * **Naming Convention:** Prefixed with "bslog" to distinguish from other logging systems:
+ * - Fastify Logger: request.log.info/error (HTTP lifecycle)
+ * - Execution Logger: executionLogger.logError (AI execution tracking)
+ * - Better Stack Logger: bslog*() (production error tracking & alerts)
+ *
+ * **When to Use:**
+ * - External service failures (OpenAI, WorkOS, OAuth) - global handler can't infer service name
+ * - Execution failures - global handler can't infer execution phase/resource type
+ * - System errors only (use isSystemError() to filter 5xx vs 4xx)
+ *
+ * **When NOT to Use:**
+ * - User errors (4xx validation, auth checks) - too noisy
+ * - WebSocket/SSE/Database errors - global handler already logs these
+ * - Generic errors - global handler already logs these
+ *
+ * All functions are no-ops unless NODE_ENV === 'production' AND API_BETTERSTACK_ERRORS_DSN is set.
+ */
+
+/**
+ * Log external service failures (OpenAI, WorkOS, OAuth providers)
+ *
+ * Use this when external API calls fail to add service-specific context
+ * that the global error handler cannot infer.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await openai.chat.completions.create(params)
+ * } catch (error) {
+ *   bslogExternalServiceError('openai', 'chat.completions.create', error, {
+ *     model: params.model,
+ *     tokens: params.max_tokens,
+ *     organizationId: executionContext.organizationId,
+ *     statusCode: (error as any).status
+ *   })
+ *   throw error
+ * }
+ * ```
+ */
+export async function bslogExternalServiceError(
+  service: 'openai' | 'workos' | 'google-oauth' | 'notion-oauth' | 'attio-oauth' | string,
+  operation: string,
+  error: Error,
+  context?: {
+    statusCode?: number
+    response?: string
+    endpoint?: string
+    organizationId?: string
+    userId?: string
+    [key: string]: unknown
+  }
+): Promise<void> {
+  if (process.env.NODE_ENV === 'production' && process.env.API_BETTERSTACK_ERRORS_DSN) {
+    // Sentry is optional - only loaded in production
+    try {
+      const Sentry = await import('@sentry/node')
+      Sentry.captureException(error, {
+        tags: {
+          layer: 'integration',
+          service,
+          operation,
+          ...(context?.statusCode && { status_code: context.statusCode })
+        },
+        user: context?.userId
+          ? {
+              id: context.userId
+            }
+          : undefined,
+        extra: {
+          service,
+          operation,
+          organizationId: context?.organizationId,
+          endpoint: context?.endpoint,
+          response: context?.response,
+          ...context
+        }
+      })
+    } catch {
+      // Sentry not available - skip logging
+    }
+  }
+}
+
+/**
+ * Log workflow/agent execution failures
+ *
+ * Use this for critical business logic failures to add execution-specific
+ * context that the global error handler cannot infer.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   return await this.runExecution(params)
+ * } catch (error) {
+ *   bslogExecutionFailure({
+ *     executionId: execution.id,
+ *     resourceType: params.resourceType,
+ *     resourceId: params.resourceId,
+ *     organizationId: params.organizationId,
+ *     userId: params.userId,
+ *     inputType: typeof params.input,
+ *     errorPhase: 'execution'
+ *   }, error as Error)
+ *   throw error
+ * }
+ * ```
+ */
+export async function bslogExecutionFailure(
+  executionContext: {
+    executionId?: string
+    resourceType: 'workflow' | 'agent'
+    resourceId: string
+    organizationId: string
+    userId?: string
+    inputType?: string
+    errorPhase?: 'initialization' | 'execution' | 'completion' | 'cleanup'
+  },
+  error: Error
+): Promise<void> {
+  if (process.env.NODE_ENV === 'production' && process.env.API_BETTERSTACK_ERRORS_DSN) {
+    try {
+      const Sentry = await import('@sentry/node')
+      const domainTags =
+        error instanceof ExecutionError
+          ? {
+              error_type_domain: error.type,
+              error_severity: error.severity,
+              error_category: error.category,
+              is_retryable: String(error.isRetryable())
+            }
+          : {}
+
+      Sentry.captureException(error, {
+        tags: {
+          layer: 'execution',
+          resource_type: executionContext.resourceType,
+          organization_id: executionContext.organizationId,
+          error_phase: executionContext.errorPhase || 'execution',
+          ...domainTags
+        },
+        user: executionContext.userId
+          ? {
+              id: executionContext.userId
+            }
+          : undefined,
+        extra: {
+          executionId: executionContext.executionId,
+          resourceType: executionContext.resourceType,
+          resourceId: executionContext.resourceId,
+          organizationId: executionContext.organizationId,
+          inputType: executionContext.inputType,
+          errorPhase: executionContext.errorPhase
+        }
+      })
+    } catch {
+      // Sentry not available - skip logging
+    }
+  }
+}
+
+/**
+ * Helper: Check if error should be logged to Better Stack
+ *
+ * Returns true for system errors (5xx), false for user errors (4xx)
+ *
+ * Use this to filter out validation errors and auth failures that
+ * would create noise in Better Stack.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (isSystemError(error)) {
+ *     bslogExternalServiceError('openai', 'completion', error, { ... })
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export function isSystemError(error: unknown): boolean {
+  // Check if error has a status code property (common in HTTP errors)
+  if (error && typeof error === 'object') {
+    const statusCode =
+      ('statusCode' in error && typeof error.statusCode === 'number' && error.statusCode) ||
+      ('status' in error && typeof error.status === 'number' && error.status) ||
+      ('code' in error && typeof error.code === 'number' && error.code)
+
+    if (statusCode) {
+      // 5xx = system error (log it)
+      // 4xx = user error (don't log)
+      return statusCode >= 500
+    }
+  }
+
+  // If no status code, assume it's a system error (better to over-log than under-log)
+  return true
+}

package/src/platform/utils/server/hmac.ts

@@ -0,0 +1,44 @@
+/**
+ * HMAC Token Utilities
+ *
+ * Generic HMAC-based token generation and verification.
+ * Used for unsubscribe links, brochure personalization, and other marketing URLs.
+ */
+
+import crypto from 'crypto'
+
+/**
+ * Generate HMAC-SHA256 token for any data
+ *
+ * @param data - Data to sign (email, contactId, etc.)
+ * @param secret - HMAC secret key (HMAC_SECRET)
+ * @returns 16-character hex token
+ */
+export function generateHmacToken(data: string, secret: string): string {
+  return crypto
+    .createHmac('sha256', secret)
+    .update(data.toLowerCase().trim())
+    .digest('hex')
+    .slice(0, 16)
+}
+
+/**
+ * Verify HMAC token using timing-safe comparison
+ */
+export function verifyHmacToken(data: string, token: string, secret: string): boolean {
+  const expected = generateHmacToken(data, secret)
+  if (token.length !== expected.length) return false
+  return crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected))
+}
+
+/**
+ * Generate brochure URL with token
+ */
+export function generateBrochureUrl(
+  contactId: string,
+  secret: string,
+  baseUrl = 'https://brochure.elevasis.io'
+): string {
+  const token = generateHmacToken(contactId, secret)
+  return `${baseUrl}/${contactId}?t=${token}`
+}

package/src/platform/utils/server/unsubscribe.ts

@@ -0,0 +1,111 @@
+/**
+ * Unsubscribe Token Utilities
+ *
+ * HMAC-based token generation and verification for one-click unsubscribe
+ * compliance with RFC 8058 (Gmail/Yahoo/Microsoft requirements).
+ *
+ * @example
+ * ```typescript
+ * import { generateUnsubscribeToken, verifyUnsubscribeToken } from '@repo/core/server'
+ *
+ * // Generate token for email link
+ * const token = generateUnsubscribeToken('john@example.com', process.env.UNSUBSCRIBE_SECRET!)
+ * const url = `https://api.elevasis.io/api/unsubscribe?email=john@example.com&token=${token}`
+ *
+ * // Verify token on POST request
+ * const isValid = verifyUnsubscribeToken('john@example.com', token, process.env.UNSUBSCRIBE_SECRET!)
+ * ```
+ */
+
+import crypto from 'crypto'
+
+/**
+ * Generate HMAC-SHA256 token for unsubscribe verification
+ *
+ * Uses first 16 characters of the hash for URL-friendly tokens.
+ *
+ * @param email - Email address to generate token for
+ * @param secret - HMAC secret key (HMAC_SECRET)
+ * @returns 16-character hex token
+ */
+export function generateUnsubscribeToken(email: string, secret: string): string {
+  return crypto.createHmac('sha256', secret).update(email.toLowerCase().trim()).digest('hex').slice(0, 16)
+}
+
+/**
+ * Verify unsubscribe token using timing-safe comparison
+ *
+ * Prevents timing attacks by using constant-time comparison.
+ *
+ * @param email - Email address to verify
+ * @param token - Token from request
+ * @param secret - HMAC secret key (HMAC_SECRET)
+ * @returns true if token is valid
+ */
+export function verifyUnsubscribeToken(email: string, token: string, secret: string): boolean {
+  const expected = generateUnsubscribeToken(email, secret)
+
+  // Ensure both are same length before comparison
+  if (token.length !== expected.length) {
+    return false
+  }
+
+  const tokenBuf = Buffer.from(token)
+  const expectedBuf = Buffer.from(expected)
+
+  return crypto.timingSafeEqual(tokenBuf, expectedBuf)
+}
+
+/**
+ * Generate unsubscribe URL with token
+ *
+ * @param email - Email address
+ * @param secret - HMAC secret key
+ * @param baseUrl - Base URL for unsubscribe endpoint (default: production URL)
+ * @returns Full unsubscribe URL with email and token query params
+ */
+export function generateUnsubscribeUrl(
+  email: string,
+  secret: string,
+  baseUrl = 'https://api.elevasis.io/api/unsubscribe'
+): string {
+  const token = generateUnsubscribeToken(email, secret)
+  const encodedEmail = encodeURIComponent(email.toLowerCase().trim())
+  return `${baseUrl}?email=${encodedEmail}&token=${token}`
+}
+
+/**
+ * Generate List-Unsubscribe headers for RFC 8058 compliance
+ *
+ * Returns headers object to include in Resend email headers parameter.
+ *
+ * @param email - Recipient email address
+ * @param secret - HMAC secret key
+ * @param baseUrl - Base URL for unsubscribe endpoint
+ * @returns Headers object with List-Unsubscribe and List-Unsubscribe-Post
+ *
+ * @example
+ * ```typescript
+ * const headers = generateUnsubscribeHeaders('john@example.com', secret)
+ * // Use in Resend:
+ * await resend.emails.send({
+ *   from: 'sender@domain.com',
+ *   to: 'john@example.com',
+ *   subject: 'Subject',
+ *   html: '<p>Content</p>',
+ *   headers
+ * })
+ * ```
+ */
+export function generateUnsubscribeHeaders(
+  email: string,
+  secret: string,
+  baseUrl = 'https://api.elevasis.io/api/unsubscribe'
+): Record<string, string> {
+  const url = generateUnsubscribeUrl(email, secret, baseUrl)
+
+  return {
+    'List-Unsubscribe': `<${url}>`,
+    'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
+  }
+}