npm package: @ginia/events
Description: SDK for emitting domain events to the Ginia Events API
Latest version: 0.2.1

# @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

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

## Usage

### 1. Configuration

Initialize the `EventEmitter` with your API configuration.

```typescript
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.

```typescript
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

```bash
# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test
```

## Publishing a New Version

1. Make your changes and ensure tests pass:

```bash
pnpm test
```

2. Build the package:

```bash
pnpm build
```

3. Bump the version in `package.json` following [semver](https://semver.org/):
   - **patch** (0.2.0 → 0.2.1): bug fixes
   - **minor** (0.2.0 → 0.3.0): new features, backward-compatible
   - **major** (0.2.0 → 1.0.0): breaking changes

4. Commit and push:

```bash
git add .
git commit -m "chore: bump version to x.y.z"
git push origin main
```

5. Publish to npm (requires OTP from your authenticator app):

```bash
npm publish --access public --otp=<YOUR_OTP_CODE>
```

6. Update the dependency in consumer projects (admin-hub, candidates-hub, etc.):

```bash
pnpm update @ginia/events
```

## License

MIT