npm package: @materi.ai/proto
Description: Materi Event Schema - TypeScript bindings for Protocol Buffer event definitions
Author: Materi
Latest version: 0.1.3

# @materi/proto

TypeScript bindings for Materi Event Schema - Protocol Buffer event definitions for the Materi collaboration platform.

## Installation

```bash
npm install @materi/proto
# or
yarn add @materi/proto
# or
pnpm add @materi/proto
```

## Usage

### Basic Import

```typescript
import {
    DomainEvent,
    UserCreatedEvent,
    DocumentCreatedEvent,
    Status,
    SourceService,
} from '@materi/proto';

// Create a user event
const event: UserCreatedEvent = {
    userId: 'user-123',
    email: 'alice@example.com',
    name: 'Alice',
    createdAt: new Date(),
};
```

### Serialization

```typescript
import { UserCreatedEvent } from '@materi/proto';

// Create event
const event: UserCreatedEvent = {
    userId: 'user-123',
    email: 'alice@example.com',
    name: 'Alice',
};

// Encode to binary
const bytes = UserCreatedEvent.encode(event).finish();

// Decode from binary
const decoded = UserCreatedEvent.decode(bytes);
console.log(decoded.email); // 'alice@example.com'
```

### JSON Serialization

```typescript
import { UserCreatedEvent } from '@materi/proto';

const event: UserCreatedEvent = {
    userId: 'user-123',
    email: 'alice@example.com',
    name: 'Alice',
};

// To JSON
const json = UserCreatedEvent.toJSON(event);

// From JSON
const parsed = UserCreatedEvent.fromJSON(json);
```

### Domain Event Envelope

```typescript
import { DomainEvent } from '@materi/proto';

const envelope: DomainEvent = {
    eventId: 'evt-456',
    eventType: 'user.created',
    aggregateId: 'user-123',
    aggregateType: 'user',
    version: 1,
    occurredAt: new Date(),
    publishedAt: new Date(),
    sourceService: 'api',
    userId: 'system',
    correlationId: 'req-789',
    traceId: 'trace-abc',
    spanId: 'span-def',
};
```

## Available Domains

### Envelope (Core)
- `DomainEvent` - Universal event envelope
- `EventAcknowledgment` - Consumer acknowledgment

### User Domain
- `UserCreatedEvent`
- `UserUpdatedEvent`
- `UserDeletedEvent`
- `UserLoginEvent`
- `UserLogoutEvent`
- `UserPasswordChangedEvent`
- `UserMFAEnabledEvent`
- `UserMFADisabledEvent`
- `UserLoginFailedEvent`
- `UserLockedEvent`
- `UserUnlockedEvent`

### Document Domain
- `DocumentCreatedEvent`
- `DocumentUpdatedEvent`
- `DocumentDeletedEvent`
- `DocumentSharedEvent`

### Workspace Domain
- `WorkspaceCreatedEvent`
- `WorkspaceUpdatedEvent`
- `WorkspaceMemberAddedEvent`
- `WorkspaceMemberRemovedEvent`
- `WorkspaceDeletedEvent`

### Collaboration Domain
- `CollaborationSessionStartedEvent`
- `CollaborationSessionEndedEvent`
- `OperationAppliedEvent`
- `PresenceUpdatedEvent`
- `ConflictResolvedEvent`

### Aria (AI/ML) Domain
- `AriaAnalysisStartedEvent`
- `AriaAnalysisCompleteEvent`
- `AriaAnalysisFailedEvent`
- `AriaSafetyGatePassedEvent`
- `AriaSafetyGateBlockedEvent`

### Notification Domain
- `EmailSentEvent`
- `EmailDeliveryFailedEvent`
- `NotificationPublishedEvent`
- `NotificationReadEvent`

### Audit Domain
- `PermissionDeniedEvent`
- `DataAccessLoggedEvent`
- `AuditLogCreatedEvent`

### Shared Types
- `Status` - Entity status enum
- `SourceService` - Service identifier enum
- `PermissionLevel` - Permission level enum
- `OperationType` - Operation type enum
- `EventMetadata` - Event metadata
- `AggregateMetadata` - Aggregate metadata
- `SchemaMetadata` - Schema metadata

## Direct Domain Access

For granular imports:

```typescript
// Import from specific domain
import { UserCreatedEvent } from '@materi/proto/domains/user';
import { DocumentCreatedEvent } from '@materi/proto/domains/document';
```

## TypeScript Support

This package includes full TypeScript type definitions:

```typescript
import type { UserCreatedEvent, DomainEvent } from '@materi/proto';

function processEvent(event: DomainEvent): void {
    console.log(event.eventId);
}

function createUser(data: Partial<UserCreatedEvent>): UserCreatedEvent {
    return {
        userId: data.userId ?? '',
        email: data.email ?? '',
        name: data.name ?? '',
        ...data,
    };
}
```

## Module Formats

This package supports both ESM and CommonJS:

```javascript
// ESM
import { UserCreatedEvent } from '@materi/proto';

// CommonJS
const { UserCreatedEvent } = require('@materi/proto');
```

## Development

### Regenerate from Proto

```bash
# From ts/ directory
npm run generate

# Or from root
make compile-ts
```

### Build

```bash
npm run build
```

### Type Check

```bash
npm run typecheck
```

## Requirements

- Node.js >= 18.0.0
- TypeScript >= 5.0 (for development)

## Related Packages

- Go: `github.com/materi/domain/proto`
- Python: `materi-proto` (PyPI)

## License

MIT