@openfloor/protocol
Version:
Open Floor Protocol implementation for JavaScript/TypeScript - enables interoperable multi-agent conversations
354 lines • 11 kB
TypeScript
/**
* @fileoverview Envelope and Manifest implementation for the Open Floor Protocol
* Implements the Inter-Agent Message Specification v1.0.0 and Assistant Manifest Specification v1.0.0
* @author Open Voice Interoperability Initiative
* @version 0.0.1
* @license Apache-2.0
*/
import { SchemaOptions, IdentificationOptions, SupportedLayersOptions, CapabilityOptions, ManifestOptions, ConversantOptions, ConversationOptions, SenderOptions, ToOptions, BaseEventOptions, EnvelopeOptions, PayloadOptions, JsonSerializable } from './types';
/**
* Represents schema information for Open Floor protocol messages
*
* @example
* ```typescript
* const schema = new Schema({ version: '1.0.0' });
* const schemaWithUrl = new Schema({
* version: '1.0.0',
* url: 'https://example.com/schema.json'
* });
* ```
*/
export declare class Schema implements JsonSerializable {
readonly version: string;
readonly url?: string;
/**
* Creates a new Schema instance
* @param options - Schema configuration options
*/
constructor(options: SchemaOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Schema;
}
/**
* Represents identification information for an agent or conversant
*
* @example
* ```typescript
* const identification = new Identification({
* speakerUri: 'tag:example.com,2025:agent1',
* serviceUrl: 'https://example.com/agent',
* organization: 'Example Corp',
* conversationalName: 'Assistant',
* synopsis: 'Helpful AI assistant'
* });
* ```
*/
export declare class Identification implements JsonSerializable {
readonly speakerUri: string;
readonly serviceUrl: string;
readonly organization?: string;
readonly conversationalName?: string;
readonly department?: string;
readonly role?: string;
readonly synopsis?: string;
/**
* Creates a new Identification instance
* @param options - Identification configuration options
* @throws Error if required fields are missing or invalid
*/
constructor(options: IdentificationOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Identification;
}
/**
* Represents supported input/output layers for agent capabilities
*
* @example
* ```typescript
* const layers = new SupportedLayers({
* input: ['text', 'audio'],
* output: ['text', 'ssml', 'audio']
* });
* ```
*/
export declare class SupportedLayers implements JsonSerializable {
readonly input: readonly string[];
readonly output: readonly string[];
/**
* Creates a new SupportedLayers instance
* @param options - SupportedLayers configuration options
*/
constructor(options?: SupportedLayersOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): SupportedLayers;
}
/**
* Represents a single capability of an agent
*
* @example
* ```typescript
* const capability = new Capability({
* keyphrases: ['weather', 'forecast', 'temperature'],
* descriptions: ['Provides weather information and forecasts'],
* languages: ['en-US', 'en-GB'],
* supportedLayers: { input: ['text'], output: ['text', 'ssml'] }
* });
* ```
*/
export declare class Capability implements JsonSerializable {
readonly keyphrases: readonly string[];
readonly descriptions: readonly string[];
readonly languages?: readonly string[];
readonly supportedLayers: SupportedLayers;
/**
* Creates a new Capability instance
* @param options - Capability configuration options
* @throws Error if required fields are missing
*/
constructor(options: CapabilityOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Capability;
}
/**
* Represents an agent manifest containing identification and capabilities
*
* @example
* ```typescript
* const manifest = new Manifest({
* identification: {
* speakerUri: 'tag:example.com,2025:weather-bot',
* serviceUrl: 'https://example.com/weather-bot',
* organization: 'Weather Corp',
* conversationalName: 'WeatherBot',
* synopsis: 'Weather information assistant'
* },
* capabilities: [{
* keyphrases: ['weather', 'forecast'],
* descriptions: ['Provides weather forecasts and current conditions']
* }]
* });
* ```
*/
export declare class Manifest implements JsonSerializable {
readonly identification: Identification;
readonly capabilities: readonly Capability[];
/**
* Creates a new Manifest instance
* @param options - Manifest configuration options
* @throws Error if required fields are missing
*/
constructor(options: ManifestOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Manifest;
}
/**
* Represents a conversant in a conversation with identification and persistent state
*
* @example
* ```typescript
* const conversant = new Conversant({
* identification: {
* speakerUri: 'tag:example.com,2025:user1',
* serviceUrl: 'https://example.com/user-proxy',
* conversationalName: 'User'
* },
* persistentState: { preferences: { language: 'en-US' } }
* });
* ```
*/
export declare class Conversant implements JsonSerializable {
readonly identification: Identification;
readonly persistentState: Record<string, unknown>;
/**
* Creates a new Conversant instance
* @param options - Conversant configuration options
* @throws Error if identification is missing
*/
constructor(options: ConversantOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Conversant;
}
/**
* Represents conversation metadata including ID and participants
*
* @example
* ```typescript
* const conversation = new Conversation({
* id: 'conv:12345',
* conversants: [{
* identification: {
* speakerUri: 'tag:example.com,2025:user1',
* serviceUrl: 'https://example.com/user-proxy'
* }
* }]
* });
* ```
*/
export declare class Conversation implements JsonSerializable {
readonly id: string;
readonly conversants: readonly Conversant[];
/**
* Creates a new Conversation instance
* @param options - Conversation configuration options
*/
constructor(options: ConversationOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Conversation;
}
/**
* Represents sender information for envelope messages
*
* @example
* ```typescript
* const sender = new Sender({
* speakerUri: 'tag:example.com,2025:agent1',
* serviceUrl: 'https://example.com/agent'
* });
* ```
*/
export declare class Sender implements JsonSerializable {
readonly speakerUri: string;
readonly serviceUrl?: string;
/**
* Creates a new Sender instance
* @param options - Sender configuration options
* @throws Error if speakerUri is missing or invalid
*/
constructor(options: SenderOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Sender;
}
/**
* Represents targeting information for events (who the event is addressed to)
*
* @example
* ```typescript
* // Address to specific agent
* const to1 = new To({
* speakerUri: 'tag:example.com,2025:agent1'
* });
*
* // Private message to specific service
* const to2 = new To({
* serviceUrl: 'https://example.com/agent',
* private: true
* });
* ```
*/
export declare class To implements JsonSerializable {
readonly speakerUri?: string;
readonly serviceUrl?: string;
readonly private: boolean;
/**
* Creates a new To instance
* @param options - To configuration options
* @throws Error if neither speakerUri nor serviceUrl is provided
*/
constructor(options: ToOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): To;
}
/**
* Base class for all Open Floor Protocol events
*
* @example
* ```typescript
* const event = new Event({
* eventType: 'utterance',
* to: { speakerUri: 'tag:example.com,2025:agent1' },
* reason: 'User query',
* parameters: { dialogEvent: {...} }
* });
* ```
*/
export declare class Event implements JsonSerializable {
readonly eventType: string;
readonly to?: To;
readonly reason?: string;
readonly parameters: Record<string, unknown>;
/**
* Creates a new Event instance
* @param options - Event configuration options
* @throws Error if eventType is missing or invalid
*/
constructor(options: BaseEventOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Event;
}
/**
* Represents an Open Floor Protocol message envelope
* Contains schema, conversation, sender, and events information
*
* @example
* ```typescript
* const envelope = new Envelope({
* conversation: { id: 'conv:12345' },
* sender: { speakerUri: 'tag:example.com,2025:agent1' },
* events: [{
* eventType: 'utterance',
* parameters: { dialogEvent: {...} }
* }]
* });
* ```
*/
export declare class Envelope implements JsonSerializable {
readonly schema: Schema;
readonly conversation: Conversation;
readonly sender: Sender;
readonly events: readonly Event[];
/**
* Creates a new Envelope instance
* @param options - Envelope configuration options
* @throws Error if required fields are missing
*/
constructor(options: EnvelopeOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
/**
* Creates a wrapped payload for the envelope (adds openFloor wrapper)
*/
toPayload(): Payload;
static fromObject(data: Record<string, unknown>): Envelope;
}
/**
* Represents a payload wrapper that contains an Open Floor envelope
* This is the top-level structure as defined in the specification
*
* @example
* ```typescript
* const payload = new Payload({
* openFloor: {
* conversation: { id: 'conv:12345' },
* sender: { speakerUri: 'tag:example.com,2025:agent1' },
* events: []
* }
* });
* ```
*/
export declare class Payload implements JsonSerializable {
readonly openFloor: Envelope;
/**
* Creates a new Payload instance
* @param options - Payload configuration options
* @throws Error if openFloor is missing
*/
constructor(options: PayloadOptions);
toObject(): Record<string, unknown>;
toJSON(): string;
static fromObject(data: Record<string, unknown>): Payload;
/**
* Creates a Payload from a JSON string
*/
static fromJSON(jsonString: string): Payload;
}
//# sourceMappingURL=envelope.d.ts.map