@materi/proto

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

Installation

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

Usage

Basic Import

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

// Create a user event
const event: UserCreatedEvent = {
    userId: 'user-123',
    email: '[email protected]',
    name: 'Alice',
    createdAt: new Date(),
};

Serialization

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

// Create event
const event: UserCreatedEvent = {
    userId: 'user-123',
    email: '[email protected]',
    name: 'Alice',
};

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

// Decode from binary
const decoded = UserCreatedEvent.decode(bytes);
console.log(decoded.email); // '[email protected]'

JSON Serialization

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

const event: UserCreatedEvent = {
    userId: 'user-123',
    email: '[email protected]',
    name: 'Alice',
};

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

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

Domain Event Envelope

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:

// 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:

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:

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

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

Development

Regenerate from Proto

# From ts/ directory
npm run generate

# Or from root
make compile-ts

Build

npm run build

Type Check

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