@ginia/events

SDK for emitting domain events to the Ginia Events API.

Features

• Simple Integration: Easy-to-use EventEmitter class.
• Auto-configuration: Automatically generates event_id (UUID v4) and occurred_at (ISO 8601).
• Type Safety: Full TypeScript support with exported types for events and entities.
• Fire-and-forget: Designed to be non-blocking. Network or API errors are logged to console.error but do not throw exceptions, ensuring your main application flow is never interrupted by telemetry failures.

Installation

pnpm add @ginia/events
# or
npm install @ginia/events
# or
yarn add @ginia/events

Usage

1. Configuration

Initialize the EventEmitter with your API configuration.

import { EventEmitter } from '@ginia/events';

const events = new EventEmitter({
  apiUrl: 'https://integrations.ginia.io/events',
  apiKey: 'your-api-key', // 'sk-...'
  source: 'candidates-hub', // or 'employers-hub', 'admin-hub', etc.
});

2. Emitting Events

Use the emit method to send events. You don't need to provide event_id, occurred_at, or source as they are handled automatically.

import { EventType, EntityType } from '@ginia/events';

await events.emit({
  event_type: 'UPDATED',
  entity_type: 'candidate',
  entity_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
  payload: {
    data: { state: 'active' },
    modified_fields: ['state'],
    previous_data: { state: 'pending' },
  },
  metadata: {
    triggered_by_user_id: 'user-uuid-123',
  },
});

Configuration Options

The EventEmitter constructor accepts an object with the following properties:

| Property | Type | Description | |----------|------|-------------| | apiUrl | string | The full URL of the Events API endpoint (e.g., https://integrations.ginia.io/events). | | apiKey | string | Your unique API key for authentication. | | source | EventSource | The identifier of the service emitting the event (e.g., candidates-hub). |

Error Handling

The SDK implements a "fire-and-forget" strategy.

• Success: The emit promise resolves when the event is successfully accepted by the API (HTTP 202).
• Failure: If the API returns an error (4xx/5xx) or if there is a network issue, the promise still resolves. The error details are logged to stderr using console.error with the prefix [ginia-events].

This ensures that event emission failures do not crash your application or interrupt critical business logic.

Application Structure

The SDK exports the following main components:

• EventEmitter: Main class for sending events.
• GiniaEventsError: Error class used internally.
• EventSource, EventType, EntityType: TypeScript types for type safety.

Development

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

License

MIT