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.

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

// 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';

// 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 with SDK

import { Codmir } from '@codmir/sdk';

const codmir = new Codmir({ token: process.env.CODMIR_TOKEN });

// Emit event
await codmir.events.emit({
  type: 'ci.workflow.completed',
  payload: {
    workflowName: 'Deploy',
    conclusion: 'success',
  },
});

// Query events
const failures = await codmir.events.query({
  type: 'ci.workflow.failed',
  since: '7d',
  repository: 'my-org/my-repo',
});

// Subscribe to real-time events
codmir.events.subscribe({
  type: 'ci.*',
  onEvent: (event) => {
    console.log('CI Event:', event.type, event.payload);
  },
});

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,
  CIWorkflowPayload,
  CIJobPayload,
  CIStepPayload,
  CIFailureAnalysisPayload,
  AgentTaskPayload,
  TicketPayload,
} from '@codmir/events';

Next Steps

SDK Reference - Full SDK documentation
CI Integration - CI/CD setup guide
API Reference - REST API for events