@elevasis/core 0.1.0

package/src/execution/engine/tools/platform/email/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Platform Email Tool Types
+ *
+ * Zod schemas and inferred types for platform email sending.
+ * Supports three targeting modes: explicit userIds, role-based, or broadcast.
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// INPUT SCHEMA
+// =============================================================================
+
+/**
+ * Input schema for sending platform emails
+ *
+ * Targeting modes (exactly one required):
+ * - userIds: Explicit list of user IDs to email
+ * - targetRole: Role to target (e.g., "admin")
+ * - targetAll: Send to all org members
+ *
+ * Content (at least one required):
+ * - html: HTML email body
+ * - text: Plain text email body
+ */
+export const SendPlatformEmailInputSchema = z
+  .object({
+    // Targeting (exactly one required)
+    userIds: z.array(z.string().uuid()).optional().describe('Explicit list of user IDs to email'),
+    targetRole: z.string().optional().describe('Role to target (e.g., "admin")'),
+    targetAll: z.boolean().optional().describe('Send to all org members'),
+
+    // Content
+    subject: z.string().min(1).max(200),
+    html: z.string().optional(),
+    text: z.string().optional(),
+
+    // Optional
+    replyTo: z.string().email().optional(),
+    tags: z
+      .array(
+        z.object({
+          name: z.string(),
+          value: z.string()
+        })
+      )
+      .optional()
+  })
+  .refine(
+    (data) => {
+      const modes = [data.userIds?.length, data.targetRole, data.targetAll].filter(Boolean)
+      return modes.length === 1
+    },
+    { message: 'Exactly one targeting mode required: userIds, targetRole, or targetAll' }
+  )
+  .refine((data) => data.html || data.text, { message: 'Must provide either html or text body' })
+
+export type SendPlatformEmailInput = z.infer<typeof SendPlatformEmailInputSchema>
+
+// =============================================================================
+// OUTPUT SCHEMA
+// =============================================================================
+
+/**
+ * Output schema for platform email send result
+ * Follows partial success pattern (similar to BatchProcessResult)
+ */
+export const SendPlatformEmailOutputSchema = z.object({
+  sent: z.number().int(),
+  failed: z.number().int(),
+  errors: z
+    .array(
+      z.object({
+        userId: z.string().uuid(),
+        email: z.string().email(),
+        error: z.string()
+      })
+    )
+    .optional()
+})
+
+export type SendPlatformEmailOutput = z.infer<typeof SendPlatformEmailOutputSchema>
+
+// =============================================================================
+// TOOL CONFIG
+// =============================================================================
+
+/**
+ * Configuration for creating a platform email tool
+ */
+export interface PlatformEmailToolConfig {
+  /** Unique name for the tool */
+  name: string
+  /** Description of what the tool does (shown to LLM) */
+  description: string
+}

package/src/execution/engine/tools/platform/index.ts

@@ -0,0 +1,181 @@
+/**
+ * Platform Tools
+ * Factory functions for creating tools that interact with internal platform services
+ *
+ * Platform tools enable agents to:
+ * - Request human approval (command queue)
+ * - Schedule future execution (task scheduler)
+ * - Send platform notifications (notifications service)
+ * - Invoke other resources - agents and workflows (resource invocation)
+ *
+ * Usage:
+ * import { createApprovalTool, createSchedulerTool, createNotificationTool } from '@repo/core/execution-engine/tools/platform'
+ */
+
+export { createApprovalTool } from './approval'
+export { createSchedulerTool } from './scheduler'
+export { createNotificationTool } from './notification'
+
+export type {
+  ApprovalToolConfig,
+  SchedulerToolConfig,
+  NotificationToolConfig,
+  ICommandQueueService,
+  ITaskSchedulerService,
+  INotificationsService
+} from './types'
+
+// Platform Email Tool
+export { createPlatformEmailTool } from './email'
+
+export type { SendPlatformEmailInput, SendPlatformEmailOutput, PlatformEmailToolConfig } from './email'
+
+export { SendPlatformEmailInputSchema, SendPlatformEmailOutputSchema } from './email'
+
+// Resource Invocation (service, types, and tool factories - Wave 2a complete)
+export {
+  ResourceInvocationService,
+  createResourceInvocationService,
+  createResourceInvocationTool,
+  createDynamicResourceInvocationTool,
+  dynamicResourceInvocationSchema,
+  dynamicResourceInvocationOutputSchema
+} from './resource-invocation'
+
+export type {
+  ResourceExecutionRequest,
+  ResourceInvocationResult,
+  ResourceInvocationToolConfig,
+  ResourceDefinition
+} from './resource-invocation'
+
+// Acquisition Tools (Lead Database management)
+export {
+  // List tools
+  createAcqListCreateTool,
+  createAcqListUpdateTool,
+  createAcqListDeleteTool,
+  createAcqListListTool,
+  // Company tools
+  createAcqCompanyCreateTool,
+  createAcqCompanyUpdateTool,
+  createAcqCompanyUpsertTool,
+  createAcqCompanyGetTool,
+  createAcqCompanyListTool,
+  createAcqCompanyDeleteTool,
+  // Contact tools
+  createAcqContactCreateTool,
+  createAcqContactUpdateTool,
+  createAcqContactUpsertTool,
+  createAcqContactGetTool,
+  createAcqContactListTool,
+  createAcqContactDeleteTool,
+  createAcqContactBulkImportTool,
+  createAcqContactDeactivateByCompanyTool
+} from './acquisition'
+
+// Export acquisition types and schemas
+export type {
+  CreateListInput,
+  UpdateListInput,
+  DeleteListInput,
+  ListOutput,
+  CreateCompanyInput,
+  UpdateCompanyInput,
+  UpsertCompanyInput,
+  GetCompanyInput,
+  ListCompaniesInput,
+  DeleteCompanyInput,
+  CompanyOutput,
+  CreateContactInput,
+  UpdateContactInput,
+  UpsertContactInput,
+  GetContactInput,
+  ListContactsInput,
+  DeleteContactInput,
+  BulkImportInput,
+  ContactOutput,
+  PaginatedContactsOutput,
+  BulkImportResult,
+  DeleteResult
+} from './acquisition'
+
+// Platform Storage Tools
+export {
+  createStorageUploadTool,
+  createStorageSignedUrlTool,
+  createStorageDownloadTool,
+  createStorageDeleteTool,
+  createStorageListTool
+} from './storage'
+
+export type {
+  StorageUploadInput,
+  StorageUploadOutput,
+  StorageSignedUrlInput,
+  StorageSignedUrlOutput,
+  StorageDownloadInput,
+  StorageDownloadOutput,
+  StorageDeleteInput,
+  StorageDeleteOutput,
+  StorageListInput,
+  StorageListOutput,
+  StorageToolConfig
+} from './storage'
+
+export {
+  StorageUploadInputSchema,
+  StorageUploadOutputSchema,
+  StorageSignedUrlInputSchema,
+  StorageSignedUrlOutputSchema,
+  StorageDownloadInputSchema,
+  StorageDownloadOutputSchema,
+  StorageDeleteInputSchema,
+  StorageDeleteOutputSchema,
+  StorageListInputSchema,
+  StorageListOutputSchema
+} from './storage'
+
+// Platform PDF Tool
+export { createPdfRenderTool } from './pdf'
+
+export type { PdfRenderInput, PdfRenderOutput, PdfToolConfig } from './pdf'
+
+export { PdfRenderInputSchema, PdfRenderOutputSchema } from './pdf'
+
+// Schedule Management Tools
+export {
+  createScheduleListTool,
+  createScheduleCancelByMetadataTool,
+  createScheduleCancelByKeyTool,
+  createScheduleDeleteByKeyTool
+} from './schedules'
+
+export type {
+  ListSchedulesInput,
+  ListSchedulesOutput,
+  CancelSchedulesByMetadataInput,
+  CancelSchedulesByMetadataOutput,
+  CancelScheduleByKeyInput,
+  CancelScheduleByKeyOutput,
+  DeleteScheduleByKeyInput,
+  DeleteScheduleByKeyOutput
+} from './schedules'
+
+export {
+  ListSchedulesInputSchema,
+  ListSchedulesOutputSchema,
+  CancelSchedulesByMetadataInputSchema,
+  CancelSchedulesByMetadataOutputSchema,
+  CancelScheduleByKeyInputSchema,
+  CancelScheduleByKeyOutputSchema,
+  DeleteScheduleByKeyInputSchema,
+  DeleteScheduleByKeyOutputSchema
+} from './schedules'
+
+// HITL Cancel by Metadata Tool
+export { createHitlCancelByMetadataTool } from './approval'
+
+export type { HitlCancelByMetadataInput, HitlCancelByMetadataOutput } from './approval'
+
+export { HitlCancelByMetadataInputSchema, HitlCancelByMetadataOutputSchema } from './approval'

package/src/execution/engine/tools/platform/notification.ts

@@ -0,0 +1,81 @@
+import type { Tool, ToolExecutionOptions } from '../types'
+import { serviceUnavailable } from '../types'
+import type { CreateNotificationParams } from '../../../../operations/notifications/types'
+import { getToolServices } from '../registry'
+import type { NotificationToolConfig } from './types'
+
+/**
+ * Create a notification tool that sends platform notifications to users
+ *
+ * Notification tools enable agents and workflows to send in-app notifications
+ * to users. Notifications appear in the user's notification feed and can include
+ * action URLs for navigation.
+ *
+ * @param config - Configuration for the notification tool
+ * @returns Tool that creates notifications
+ *
+ * @example
+ * const notifyTool = createNotificationTool({
+ *   name: 'notify_user',
+ *   description: 'Send notification to user about task completion',
+ *   inputSchema: z.object({
+ *     userId: z.string(),
+ *     title: z.string(),
+ *     message: z.string(),
+ *     category: z.enum(['info', 'success', 'warning', 'error']),
+ *     actionUrl: z.string().optional()
+ *   }),
+ *   outputSchema: z.object({ notificationId: z.string() })
+ * })
+ */
+export function createNotificationTool(config: NotificationToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: config.inputSchema,
+    outputSchema: config.outputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<unknown> {
+      // ExecutionContext is required for platform tools
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', {
+          tool: config.name,
+          reason: 'organizationId required for multi-tenant isolation'
+        })
+      }
+
+      // Get notifications service from global registry
+      const { notificationsService } = getToolServices()
+      if (!notificationsService) {
+        throw serviceUnavailable('NotificationsService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      // Build notification parameters — input is validated against inputSchema before execution
+      const inputData = options.input as {
+        userId: string
+        category: string
+        title: string
+        message: string
+        actionUrl?: string
+      }
+
+      const params: CreateNotificationParams = {
+        userId: config.userId ?? inputData.userId,
+        organizationId: options.executionContext.organizationId,
+        category: config.category ?? inputData.category,
+        title: inputData.title,
+        message: inputData.message,
+        actionUrl: inputData.actionUrl
+      }
+
+      // Create notification
+      const notification = await notificationsService.create(params)
+
+      // Return notification ID for tracking
+      return { notificationId: notification.id }
+    }
+  }
+}

package/src/execution/engine/tools/platform/pdf/index.ts

@@ -0,0 +1,110 @@
+/**
+ * Platform PDF Tool
+ *
+ * Factory function for creating a PDF render tool that generates
+ * documents using pdfmake and stores them in platform storage.
+ *
+ * Usage:
+ * ```typescript
+ * const pdfTool = createPdfRenderTool({
+ *   name: 'render_pdf',
+ *   description: 'Render a PDF document and store it in platform storage'
+ * })
+ * ```
+ */
+
+import type { Tool, ToolExecutionOptions } from '../../types'
+import { serviceUnavailable } from '../../types'
+import { getToolServices } from '../../registry'
+import {
+  PdfRenderInputSchema,
+  PdfRenderOutputSchema,
+  type PdfRenderInput,
+  type PdfRenderOutput,
+  type PdfToolConfig
+} from './types'
+
+/**
+ * Create a PDF render tool for workflows and agents
+ *
+ * PDF render tools enable workflows and agents to generate PDF documents
+ * from structured data and store them in platform storage. Documents are
+ * rendered using pdfmake with configurable theming.
+ *
+ * @param config - Configuration for the PDF tool
+ * @returns Tool that renders PDFs and returns storage URLs
+ *
+ * @example
+ * const pdfTool = createPdfRenderTool({
+ *   name: 'render_proposal',
+ *   description: 'Render a proposal PDF and store in acquisition bucket'
+ * })
+ *
+ * // Execute with document structure
+ * await pdfTool.execute({
+ *   input: {
+ *     document: {
+ *       pages: [{
+ *         sections: [
+ *           { type: 'text', content: 'Proposal', variant: 'title' },
+ *           { type: 'metric', value: '$50,000', label: 'Project Value' }
+ *         ]
+ *       }]
+ *     },
+ *     storage: {
+ *       bucket: 'acquisition',
+ *       path: 'proposals/deal-123/proposal.pdf'
+ *     }
+ *   },
+ *   executionContext: context
+ * })
+ */
+export function createPdfRenderTool(config: PdfToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: PdfRenderInputSchema,
+    outputSchema: PdfRenderOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<PdfRenderOutput> {
+      // ExecutionContext is required for multi-tenant isolation
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', {
+          tool: config.name,
+          reason: 'organizationId required for multi-tenant isolation'
+        })
+      }
+
+      // Get PDF service from global registry
+      const { pdfService } = getToolServices()
+      if (!pdfService) {
+        throw serviceUnavailable('PdfService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called with pdfService in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      // Parse and validate input
+      const input = PdfRenderInputSchema.parse(options.input) as PdfRenderInput
+
+      // Render PDF via service
+      const result = await pdfService.render({
+        organizationId: options.executionContext.organizationId,
+        document: input.document,
+        theme: input.theme,
+        storage: input.storage
+      })
+
+      return result
+    }
+  }
+}
+
+// Re-export types for consumers
+export {
+  PdfRenderInputSchema,
+  PdfRenderOutputSchema,
+  type PdfRenderInput,
+  type PdfRenderOutput,
+  type PdfToolConfig
+} from './types'

package/src/execution/engine/tools/platform/pdf/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Platform PDF Tool Types
+ *
+ * Zod schemas and inferred types for PDF rendering platform tool.
+ * Supports document rendering with theme overrides and storage configuration.
+ */
+
+import { z } from 'zod'
+import { DocumentSchema } from '../../../../../business/pdf/types'
+
+// =============================================================================
+// INPUT SCHEMA
+// =============================================================================
+
+/**
+ * Storage configuration for PDF output
+ * Specifies where the rendered PDF should be stored
+ */
+export const StorageConfigSchema = z.object({
+  bucket: z.string().describe('Storage bucket name (e.g., "acquisition", "org-files")'),
+  path: z.string().describe('File path within org folder (e.g., "proposals/deal-123/proposal.pdf")')
+})
+
+/**
+ * Theme override schema (partial)
+ * Allows customizing colors, typography, and spacing for PDF rendering
+ */
+export const ThemeOverrideSchema = z
+  .object({
+    colors: z.record(z.string(), z.string()).optional().describe('Color overrides (e.g., { primary: "#1a73e8" })'),
+    typography: z.record(z.string(), z.any()).optional().describe('Typography overrides'),
+    spacing: z.record(z.string(), z.number()).optional().describe('Spacing overrides in points')
+  })
+  .optional()
+
+/**
+ * Input schema for PDF rendering tool
+ *
+ * Renders a document definition to PDF and stores it in the specified location.
+ */
+export const PdfRenderInputSchema = z.object({
+  document: DocumentSchema.describe('Document definition with pages, sections, and content blocks'),
+  theme: ThemeOverrideSchema.describe('Optional theme customization'),
+  storage: StorageConfigSchema.describe('Where to store the rendered PDF')
+})
+
+export type PdfRenderInput = z.infer<typeof PdfRenderInputSchema>
+
+// =============================================================================
+// OUTPUT SCHEMA
+// =============================================================================
+
+/**
+ * Output schema for PDF render result
+ * Returns the URL to the rendered PDF and file metadata
+ */
+export const PdfRenderOutputSchema = z.object({
+  success: z.boolean().describe('Whether the PDF was rendered and stored successfully'),
+  pdfUrl: z.string().describe('Signed URL to access the rendered PDF'),
+  size: z.number().describe('File size in bytes')
+})
+
+export type PdfRenderOutput = z.infer<typeof PdfRenderOutputSchema>
+
+// =============================================================================
+// TOOL CONFIGURATION
+// =============================================================================
+
+/**
+ * Configuration for creating a PDF render tool
+ */
+export interface PdfToolConfig {
+  /** Unique name for the tool */
+  name: string
+  /** Description of what the tool does (shown to LLM) */
+  description: string
+}