@openfloor/protocol
Version:
Open Floor Protocol implementation for JavaScript/TypeScript - enables interoperable multi-agent conversations
361 lines • 10.9 kB
TypeScript
/**
* @fileoverview Event classes for the Open Floor Protocol
* Implements all event types from the Inter-Agent Message Specification v1.0.0
* @author Open Voice Interoperability Initiative
* @version 0.0.1
* @license Apache-2.0
*/
import { UtteranceEventOptions, ContextEventOptions, GetManifestsEventOptions, PublishManifestsEventOptions, RecommendScope, ToOptions } from './types';
import { Event } from './envelope';
import { DialogEvent, DialogHistory } from './dialog-event';
import { Manifest } from './envelope';
/**
* Represents an utterance event containing spoken or written dialog
* This is the primary communication event between conversants
*
* @example
* ```typescript
* const utteranceEvent = new UtteranceEvent({
* dialogEvent: {
* speakerUri: 'tag:example.com,2025:user1',
* features: {
* text: { mimeType: 'text/plain', tokens: [{ value: 'Hello world' }] }
* }
* },
* to: { speakerUri: 'tag:example.com,2025:agent1' }
* });
* ```
*/
export declare class UtteranceEvent extends Event {
readonly dialogEvent: DialogEvent;
/**
* Creates a new UtteranceEvent instance
* @param options - UtteranceEvent configuration options
* @throws Error if dialogEvent is missing
*/
constructor(options: UtteranceEventOptions);
static fromObject(data: Record<string, unknown>): UtteranceEvent;
}
/**
* Represents a context event providing additional information to recipient agents
* Contains dialog history and other contextual parameters
*
* @example
* ```typescript
* const contextEvent = new ContextEvent({
* dialogHistory: [
* {
* speakerUri: 'tag:example.com,2025:user1',
* features: { text: { mimeType: 'text/plain', tokens: [{ value: 'Hello' }] } }
* }
* ],
* sessionData: { userId: '12345' }
* });
* ```
*/
export declare class ContextEvent extends Event {
readonly dialogHistory: DialogHistory;
/**
* Creates a new ContextEvent instance
* @param options - ContextEvent configuration options
*/
constructor(options: ContextEventOptions);
static fromObject(data: Record<string, unknown>): ContextEvent;
}
/**
* Represents an invitation for an agent to join the conversation
* This is a bare event with no required parameters
*
* @example
* ```typescript
* const inviteEvent = new InviteEvent({
* to: { serviceUrl: 'https://example.com/agent' }
* });
* ```
*/
export declare class InviteEvent extends Event {
/**
* Creates a new InviteEvent instance
* @param options - InviteEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): InviteEvent;
}
/**
* Represents removing an agent from the conversation
* Supports reason tokens for why the agent is being uninvited
*
* @example
* ```typescript
* const uninviteEvent = new UninviteEvent({
* to: { speakerUri: 'tag:example.com,2025:agent1' },
* reason: '@timedOut'
* });
* ```
*/
export declare class UninviteEvent extends Event {
/**
* Creates a new UninviteEvent instance
* @param options - UninviteEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): UninviteEvent;
}
/**
* Represents declining an invitation to join the conversation
* Sent in response to an invite event
*
* @example
* ```typescript
* const declineEvent = new DeclineInviteEvent({
* to: { speakerUri: 'tag:example.com,2025:convener' },
* reason: '@unavailable'
* });
* ```
*/
export declare class DeclineInviteEvent extends Event {
/**
* Creates a new DeclineInviteEvent instance
* @param options - DeclineInviteEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): DeclineInviteEvent;
}
/**
* Represents an agent leaving the conversation
* This is a bare event with no required parameters
*
* @example
* ```typescript
* const byeEvent = new ByeEvent({
* reason: 'Task completed'
* });
* ```
*/
export declare class ByeEvent extends Event {
/**
* Creates a new ByeEvent instance
* @param options - ByeEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): ByeEvent;
}
/**
* Represents a request for agent manifests
* Used for agent discovery and capability determination
*
* @example
* ```typescript
* const getManifestsEvent = new GetManifestsEvent({
* to: { serviceUrl: 'https://example.com/discovery-agent' },
* recommendScope: 'external'
* });
* ```
*/
export declare class GetManifestsEvent extends Event {
readonly recommendScope: RecommendScope;
/**
* Creates a new GetManifestsEvent instance
* @param options - GetManifestsEvent configuration options
*/
constructor(options: GetManifestsEventOptions);
static fromObject(data: Record<string, unknown>): GetManifestsEvent;
}
/**
* Represents publishing agent manifests
* Contains arrays of servicing and discovery manifests
*
* @example
* ```typescript
* const publishEvent = new PublishManifestsEvent({
* servicingManifests: [{
* identification: {
* speakerUri: 'tag:example.com,2025:weather-bot',
* serviceUrl: 'https://example.com/weather'
* },
* capabilities: []
* }],
* discoveryManifests: []
* });
* ```
*/
export declare class PublishManifestsEvent extends Event {
readonly servicingManifests: readonly Manifest[];
readonly discoveryManifests: readonly Manifest[];
/**
* Creates a new PublishManifestsEvent instance
* @param options - PublishManifestsEvent configuration options
*/
constructor(options: PublishManifestsEventOptions);
static fromObject(data: Record<string, unknown>): PublishManifestsEvent;
}
/**
* Represents a request for the conversational floor
* Used in multi-party conversations for floor management
*
* @example
* ```typescript
* const requestFloorEvent = new RequestFloorEvent({
* to: { speakerUri: 'tag:example.com,2025:convener' },
* reason: 'Need to add information'
* });
* ```
*/
export declare class RequestFloorEvent extends Event {
/**
* Creates a new RequestFloorEvent instance
* @param options - RequestFloorEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): RequestFloorEvent;
}
/**
* Represents granting the conversational floor to an agent
* Used by convener agents to manage multi-party conversations
*
* @example
* ```typescript
* const grantFloorEvent = new GrantFloorEvent({
* to: { speakerUri: 'tag:example.com,2025:agent1' }
* });
* ```
*/
export declare class GrantFloorEvent extends Event {
/**
* Creates a new GrantFloorEvent instance
* @param options - GrantFloorEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): GrantFloorEvent;
}
/**
* Represents revoking the conversational floor from an agent
* Used by convener agents with special reason tokens
*
* @example
* ```typescript
* const revokeFloorEvent = new RevokeFloorEvent({
* to: { speakerUri: 'tag:example.com,2025:agent1' },
* reason: '@timedOut'
* });
* ```
*/
export declare class RevokeFloorEvent extends Event {
/**
* Creates a new RevokeFloorEvent instance
* @param options - RevokeFloorEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): RevokeFloorEvent;
}
/**
* Represents yielding the conversational floor
* Sent by agents to indicate they no longer wish to speak
*
* @example
* ```typescript
* const yieldFloorEvent = new YieldFloorEvent({
* reason: '@complete'
* });
* ```
*/
export declare class YieldFloorEvent extends Event {
/**
* Creates a new YieldFloorEvent instance
* @param options - YieldFloorEvent configuration options
*/
constructor(options?: {
to?: ToOptions;
reason?: string;
});
static fromObject(data: Record<string, unknown>): YieldFloorEvent;
}
/**
* Event factory function to create appropriate event instances from generic event data
* Automatically determines the correct event class based on eventType
*
* @param data - Raw event data object
* @returns Appropriate Event instance
* @throws Error if eventType is unknown
*
* @example
* ```typescript
* const eventData = {
* eventType: 'utterance',
* parameters: { dialogEvent: {...} }
* };
* const event = createEvent(eventData); // Returns UtteranceEvent instance
* ```
*/
export declare function createEvent(data: Record<string, unknown>): Event;
/**
* Type guard to check if an event is an UtteranceEvent
*/
export declare function isUtteranceEvent(event: Event): event is UtteranceEvent;
/**
* Type guard to check if an event is a ContextEvent
*/
export declare function isContextEvent(event: Event): event is ContextEvent;
/**
* Type guard to check if an event is an InviteEvent
*/
export declare function isInviteEvent(event: Event): event is InviteEvent;
/**
* Type guard to check if an event is an UninviteEvent
*/
export declare function isUninviteEvent(event: Event): event is UninviteEvent;
/**
* Type guard to check if an event is a DeclineInviteEvent
*/
export declare function isDeclineInviteEvent(event: Event): event is DeclineInviteEvent;
/**
* Type guard to check if an event is a ByeEvent
*/
export declare function isByeEvent(event: Event): event is ByeEvent;
/**
* Type guard to check if an event is a GetManifestsEvent
*/
export declare function isGetManifestsEvent(event: Event): event is GetManifestsEvent;
/**
* Type guard to check if an event is a PublishManifestsEvent
*/
export declare function isPublishManifestsEvent(event: Event): event is PublishManifestsEvent;
/**
* Type guard to check if an event is a RequestFloorEvent
*/
export declare function isRequestFloorEvent(event: Event): event is RequestFloorEvent;
/**
* Type guard to check if an event is a GrantFloorEvent
*/
export declare function isGrantFloorEvent(event: Event): event is GrantFloorEvent;
/**
* Type guard to check if an event is a RevokeFloorEvent
*/
export declare function isRevokeFloorEvent(event: Event): event is RevokeFloorEvent;
/**
* Type guard to check if an event is a YieldFloorEvent
*/
export declare function isYieldFloorEvent(event: Event): event is YieldFloorEvent;
export { Event };
//# sourceMappingURL=events.d.ts.map