@codmir/events

Event system SDK for observability, telemetry, AI task scheduling, and workflow automation.

Features

• Telemetry — Batch event reporting to Codmir Events Platform with retries
• Event Bus Client — Publish/subscribe to events across services
• AI Task Scheduler — Schedule and delegate tasks between AI agents
• Workflow Schema — Visual workflow definitions with 8 node types
• Core Event System — Typed events, monitoring, logging, replay
• NestJS Integration — Ready-to-use modules and decorators

Installation

pnpm add @codmir/events

Telemetry (Recommended)

Track events from any project and report them to the Codmir Events Platform.

import { createTelemetry } from '@codmir/events/telemetry';

const telemetry = createTelemetry({
  endpoint: 'https://codmir.com/api/events/ingest',
  apiKey: process.env.CODMIR_EVENTS_API_KEY,
  projectId: 'proj_123',
  source: 'my-app',
  environment: 'production',
  // Optional
  batchSize: 25,        // flush after 25 events (default)
  flushIntervalMs: 5000, // auto-flush every 5s (default)
  maxRetries: 3,        // retry on 5xx errors (default)
  debug: false,         // console logging (default)
});

// Track a simple event
telemetry.track('user/signed-up', { userId: '123', plan: 'pro' });

// Track with options
telemetry.track('order/created', { orderId: 'ord_1', total: 99 }, {
  correlationId: 'checkout_abc',
  userId: 'user_456',
});

// Track an operation with automatic timing
const op = telemetry.trackOperation('deploy/build', { branch: 'main' });
await runBuild();
op.end(); // records COMPLETED + durationMs

// Handle errors
const op2 = telemetry.trackOperation('email/send');
try {
  await sendEmail();
  op2.end();
} catch (err) {
  op2.end({ error: err.message }); // records FAILED + error
}

// Manual flush
await telemetry.flush();

// Graceful shutdown (flushes remaining queue)
await telemetry.shutdown();

Telemetry Config

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | required | Ingestion API URL | | apiKey | string | — | Bearer token for auth | | projectId | string | — | Associate events with a project | | organizationId | string | — | Associate with an organization | | source | string | — | Source identifier (e.g. "my-app") | | environment | string | — | e.g. "production", "staging" | | batchSize | number | 25 | Events per batch before auto-flush | | flushIntervalMs | number | 5000 | Auto-flush interval (ms) | | maxRetries | number | 3 | Retries for server errors | | debug | boolean | false | Enable console logging | | headers | object | — | Custom request headers |

Event Bus Client

Publish and subscribe to events via the Codmir event bus.

import { createEventClient } from '@codmir/events/client';

const client = createEventClient({
  serviceUrl: 'http://localhost:3000',
  agentId: 'my-service',
  projectId: 'proj_123',
});

// Publish
await client.publish({
  type: 'ticket/created',
  data: { ticketId: 't_1', title: 'Fix login bug' },
});

// Subscribe
await client.subscribe(['task.completed', 'task.failed'], (event) => {
  console.log('Event:', event.type, event.data);
});

// Cleanup
client.close();

AI Task Scheduler

Coordinate AI agents with role-based task queuing.

import { createTaskScheduler } from '@codmir/events/scheduler';

const scheduler = createTaskScheduler({
  serviceUrl: 'http://localhost:3000',
  projectId: 'proj_123',
});

// Register as an agent
await scheduler.registerAgent({
  name: 'Coder AI',
  role: 'coder',
  capabilities: ['typescript', 'react'],
});

// Process tasks
await scheduler.startProcessing(async (task) => {
  const result = await generateCode(task.input);
  return { status: 'completed', output: { code: result } };
});

Agent Roles

| Role | Description | |------|-------------| | coordinator | Orchestrates agents, breaks down tasks | | coder | Writes and modifies code | | reviewer | Reviews code and provides feedback | | tester | Creates and runs tests | | documenter | Writes documentation | | researcher | Researches and gathers information | | planner | Creates plans and architecture | | debugger | Debugs and fixes issues | | security | Security analysis and fixes | | devops | Infrastructure and deployment |

Workflow Schema

Define visual workflows with typed nodes and edges (used in the workflow builder).

import {
  WorkflowDefinitionSchema,
  WORKFLOW_TEMPLATES,
  createWorkflowFromTemplate,
  validateWorkflow,
} from '@codmir/events';

// Create from template
const workflow = createWorkflowFromTemplate(
  'ticket-to-code', 'proj_123', 'org_456', 'user_789'
);

// Validate
const { valid, errors } = validateWorkflow(workflow);

Node Types

| Type | Description | Color | |------|-------------|-------| | trigger | Event or schedule start | Amber | | action | HTTP, DB, integration | Blue | | ai | LLM call or AI task | Purple | | condition | Branching logic (true/false) | Orange | | wait | Delay or timer | Cyan | | agent | Delegate to AI agent | Indigo | | transform | Data transformation | Teal | | output | Workflow result | Emerald |

Subpath Exports

import { ... } from '@codmir/events';           // Core + telemetry re-exports
import { ... } from '@codmir/events/telemetry';  // CodmirTelemetry, createTelemetry
import { ... } from '@codmir/events/client';      // EventClient, createEventClient
import { ... } from '@codmir/events/scheduler';   // TaskScheduler
import { ... } from '@codmir/events/orchestrator'; // Multi-agent orchestrator
import { ... } from '@codmir/events/core';        // Core types and factory
import { ... } from '@codmir/events/monitoring';  // Monitoring system
import { ... } from '@codmir/events/logging';     // Structured logging
import { ... } from '@codmir/events/replay';      // Event replay
import { ... } from '@codmir/events/adapters';    // Transport adapters
import { ... } from '@codmir/events/nestjs';      // NestJS modules
import { ... } from '@codmir/events/preview';     // IDE preview system
import { ... } from '@codmir/events/domains';     // Domain event types

Environment Variables

# Telemetry
CODMIR_EVENTS_API_KEY=your-api-key
CODMIR_EVENTS_ENDPOINT=https://codmir.com/api/events/ingest

# Event bus (legacy)
EVENTS_SERVICE_URL=http://localhost:3000
AGENT_ID=unique-agent-id
PROJECT_ID=project-123
ORGANIZATION_ID=org-456

License

MIT