Event system for real-time updates and CI/CD integration

@codmir/events

The events package provides a typed event system for emitting and subscribing to Codmir events.

Installation

npm install @codmir/events
# or included in @codmir/sdk

Event Types

CI Events

Events for CI/CD workflow tracking.

CIEventTypes and createCIWorkflowEvent aren't exported from the package root — import them from the @codmir/events/core subpath instead:

import { CIEventTypes, createCIWorkflowEvent } from '@codmir/events/core';

// Event types
CIEventTypes.WORKFLOW_QUEUED     // ci.workflow.queued
CIEventTypes.WORKFLOW_STARTED    // ci.workflow.started
CIEventTypes.WORKFLOW_COMPLETED  // ci.workflow.completed
CIEventTypes.WORKFLOW_FAILED     // ci.workflow.failed
CIEventTypes.JOB_STARTED         // ci.job.started
CIEventTypes.JOB_COMPLETED       // ci.job.completed
CIEventTypes.JOB_FAILED          // ci.job.failed
CIEventTypes.STEP_FAILED         // ci.step.failed
CIEventTypes.FAILURE_ANALYZED    // ci.failure.analyzed

Creating CI Events

import { createCIWorkflowEvent, createCIJobEvent } from '@codmir/events/core';

// Workflow event
const workflowEvent = createCIWorkflowEvent('completed', {
  provider: 'github',
  runId: 12345,
  runNumber: 42,
  workflowId: 100,
  workflowName: 'Build and Test',
  repository: 'my-org/my-repo',
  branch: 'main',
  commit: 'abc123',
  event: 'push',
  actor: 'developer',
  conclusion: 'success',
  startedAt: '2024-01-01T10:00:00Z',
  completedAt: '2024-01-01T10:05:00Z',
  durationMs: 300000,
  url: 'https://github.com/my-org/my-repo/actions/runs/12345',
});

// Job event
const jobEvent = createCIJobEvent('failed', {
  provider: 'github',
  runId: 12345,
  jobId: 67890,
  jobName: 'test',
  workflowName: 'Build and Test',
  conclusion: 'failure',
  startedAt: '2024-01-01T10:02:00Z',
  completedAt: '2024-01-01T10:04:00Z',
});

Agent Events

Events for AI agent activity.

import { AgentEventTypes, createAgentEvent } from '@codmir/events';

AgentEventTypes.TASK_STARTED     // agent.task.started
AgentEventTypes.TASK_COMPLETED   // agent.task.completed
AgentEventTypes.TOOL_CALLED      // agent.tool.called
AgentEventTypes.APPROVAL_NEEDED  // agent.approval.needed

Ticket Events

Events for ticket lifecycle.

import { TicketEventTypes } from '@codmir/events';

TicketEventTypes.CREATED         // ticket.created
TicketEventTypes.UPDATED         // ticket.updated
TicketEventTypes.ASSIGNED        // ticket.assigned
TicketEventTypes.RESOLVED        // ticket.resolved

Event Structure

All events follow a standard structure:

interface CodmirEvent<T = unknown> {
  id: string;              // Unique event ID
  type: string;            // Event type (e.g., 'ci.workflow.completed')
  timestamp: string;       // ISO timestamp
  actor: {
    type: string;          // 'user' | 'system' | 'agent'
    id: string;            // Actor identifier
  };
  session: {
    sessionId: string;     // Session/run grouping
  };
  payload: T;              // Event-specific data
  meta?: {
    causationId?: string;  // ID of causing event
    correlationId?: string;// Related events group
  };
}

Using the Event Client

import { EventClient } from '@codmir/events';

const client = new EventClient({
  serviceUrl: process.env.CODMIR_EVENTS_URL,
  apiKey: process.env.CODMIR_TOKEN,
});

// Publish an event
await client.publish({
  type: 'ci.workflow.completed',
  data: { workflowName: 'Deploy', conclusion: 'success' },
});

// Read recent events of a type
const failures = await client.getEvents('ci.workflow.failed', 50);

There's no subscribe/push-based API for real-time delivery. To react to events as they happen, build an event-triggered workflow (EventWorkflow) instead of polling or subscribing from client code.

CI Event Payloads

Workflow Payload

interface CIWorkflowPayload {
  provider: 'github' | 'gitlab' | 'jenkins';
  runId: number;
  runNumber: number;
  workflowId: number;
  workflowName: string;
  repository: string;
  branch: string | null;
  commit: string;
  event: string;           // 'push' | 'pull_request' | 'schedule'
  actor: string;
  conclusion: string | null;
  startedAt?: string;
  completedAt?: string;
  durationMs?: number;
  url?: string;
}

Job Payload

interface CIJobPayload {
  provider: 'github' | 'gitlab' | 'jenkins';
  runId: number;
  jobId: number;
  jobName: string;
  workflowName: string;
  conclusion: string | null;
  startedAt?: string;
  completedAt?: string;
  durationMs?: number;
  runnerName?: string;
  runnerLabels?: string[];
}

Failure Analysis Payload

interface CIFailureAnalysisPayload {
  runId: number;
  workflowName: string;
  failedStep: string;
  errorType: string;
  errorMessage: string;
  rootCause?: string;
  suggestedFix?: string;
  similarFailures?: number;
  confidence?: number;
  autoFixable?: boolean;
}

TypeScript Support

Full type exports:

import type {
  CodmirEvent,
  AgentTaskPayload,
  TicketPayload,
} from '@codmir/events';

// CI payload types aren't exported from the package root — import from the
// @codmir/events/core subpath instead:
import type {
  CIWorkflowPayload,
  CIJobPayload,
  CIStepPayload,
  CIFailureAnalysisPayload,
} from '@codmir/events/core';

Next Steps

SDK Reference - Full SDK documentation