@elizaos/service-interfaces 1.6.0-alpha.4

package/dist/interfaces/message.d.ts

@@ -0,0 +1,200 @@
+import { Service, type UUID } from '@elizaos/core';
+export interface MessageParticipant {
+    id: UUID;
+    name: string;
+    username?: string;
+    avatar?: string;
+    status?: 'online' | 'offline' | 'away' | 'busy';
+}
+export interface MessageAttachment {
+    id: UUID;
+    filename: string;
+    url: string;
+    mimeType: string;
+    size: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+    thumbnail?: string;
+}
+export interface MessageReaction {
+    emoji: string;
+    count: number;
+    users: UUID[];
+    hasReacted: boolean;
+}
+export interface MessageReference {
+    messageId: UUID;
+    channelId: UUID;
+    type: 'reply' | 'forward' | 'quote';
+}
+export interface MessageContent {
+    text?: string;
+    html?: string;
+    markdown?: string;
+    attachments?: MessageAttachment[];
+    reactions?: MessageReaction[];
+    reference?: MessageReference;
+    mentions?: UUID[];
+    embeds?: Array<{
+        title?: string;
+        description?: string;
+        url?: string;
+        image?: string;
+        fields?: Array<{
+            name: string;
+            value: string;
+            inline?: boolean;
+        }>;
+    }>;
+}
+export interface MessageInfo {
+    id: UUID;
+    channelId: UUID;
+    senderId: UUID;
+    content: MessageContent;
+    timestamp: Date;
+    edited?: Date;
+    deleted?: Date;
+    pinned?: boolean;
+    thread?: {
+        id: UUID;
+        messageCount: number;
+        participants: UUID[];
+        lastMessageAt: Date;
+    };
+}
+export interface MessageSendOptions {
+    replyTo?: UUID;
+    ephemeral?: boolean;
+    silent?: boolean;
+    scheduled?: Date;
+    thread?: UUID;
+    nonce?: string;
+}
+export interface MessageSearchOptions {
+    query?: string;
+    channelId?: UUID;
+    senderId?: UUID;
+    before?: Date;
+    after?: Date;
+    limit?: number;
+    offset?: number;
+    hasAttachments?: boolean;
+    pinned?: boolean;
+    mentions?: UUID;
+}
+export interface MessageChannel {
+    id: UUID;
+    name: string;
+    type: 'text' | 'voice' | 'dm' | 'group' | 'announcement' | 'thread';
+    description?: string;
+    participants?: MessageParticipant[];
+    permissions?: {
+        canSend: boolean;
+        canRead: boolean;
+        canDelete: boolean;
+        canPin: boolean;
+        canManage: boolean;
+    };
+    lastMessageAt?: Date;
+    messageCount?: number;
+    unreadCount?: number;
+}
+/**
+ * Interface for messaging services
+ */
+export declare abstract class IMessageService extends Service {
+    static readonly serviceType: "message";
+    readonly capabilityDescription = "Message sending, receiving, and management capabilities";
+    /**
+     * Send a message to a channel
+     * @param channelId - Channel ID
+     * @param content - Message content
+     * @param options - Send options
+     * @returns Promise resolving to message ID
+     */
+    abstract sendMessage(channelId: UUID, content: MessageContent, options?: MessageSendOptions): Promise<UUID>;
+    /**
+     * Get messages from a channel
+     * @param channelId - Channel ID
+     * @param options - Search options
+     * @returns Promise resolving to array of messages
+     */
+    abstract getMessages(channelId: UUID, options?: MessageSearchOptions): Promise<MessageInfo[]>;
+    /**
+     * Get a specific message by ID
+     * @param messageId - Message ID
+     * @returns Promise resolving to message
+     */
+    abstract getMessage(messageId: UUID): Promise<MessageInfo>;
+    /**
+     * Edit a message
+     * @param messageId - Message ID
+     * @param content - New message content
+     * @returns Promise resolving when edit completes
+     */
+    abstract editMessage(messageId: UUID, content: MessageContent): Promise<void>;
+    /**
+     * Delete a message
+     * @param messageId - Message ID
+     * @returns Promise resolving when deletion completes
+     */
+    abstract deleteMessage(messageId: UUID): Promise<void>;
+    /**
+     * Add a reaction to a message
+     * @param messageId - Message ID
+     * @param emoji - Reaction emoji
+     * @returns Promise resolving when reaction is added
+     */
+    abstract addReaction(messageId: UUID, emoji: string): Promise<void>;
+    /**
+     * Remove a reaction from a message
+     * @param messageId - Message ID
+     * @param emoji - Reaction emoji
+     * @returns Promise resolving when reaction is removed
+     */
+    abstract removeReaction(messageId: UUID, emoji: string): Promise<void>;
+    /**
+     * Pin a message
+     * @param messageId - Message ID
+     * @returns Promise resolving when message is pinned
+     */
+    abstract pinMessage(messageId: UUID): Promise<void>;
+    /**
+     * Unpin a message
+     * @param messageId - Message ID
+     * @returns Promise resolving when message is unpinned
+     */
+    abstract unpinMessage(messageId: UUID): Promise<void>;
+    /**
+     * Get available channels
+     * @returns Promise resolving to array of channels
+     */
+    abstract getChannels(): Promise<MessageChannel[]>;
+    /**
+     * Get channel information
+     * @param channelId - Channel ID
+     * @returns Promise resolving to channel info
+     */
+    abstract getChannel(channelId: UUID): Promise<MessageChannel>;
+    /**
+     * Create a new channel
+     * @param name - Channel name
+     * @param type - Channel type
+     * @param options - Channel options
+     * @returns Promise resolving to new channel ID
+     */
+    abstract createChannel(name: string, type: MessageChannel['type'], options?: {
+        description?: string;
+        participants?: UUID[];
+        private?: boolean;
+    }): Promise<UUID>;
+    /**
+     * Search messages across channels
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Promise resolving to search results
+     */
+    abstract searchMessages(query: string, options?: MessageSearchOptions): Promise<MessageInfo[]>;
+}

package/dist/interfaces/pdf.d.ts

@@ -0,0 +1,67 @@
+import { Service } from '@elizaos/core';
+export interface PdfExtractionResult {
+    text: string;
+    pageCount: number;
+    metadata?: {
+        title?: string;
+        author?: string;
+        createdAt?: Date;
+        modifiedAt?: Date;
+    };
+}
+export interface PdfGenerationOptions {
+    format?: 'A4' | 'A3' | 'Letter';
+    orientation?: 'portrait' | 'landscape';
+    margins?: {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    };
+    header?: string;
+    footer?: string;
+}
+export interface PdfConversionOptions {
+    quality?: 'high' | 'medium' | 'low';
+    outputFormat?: 'pdf' | 'pdf/a';
+    compression?: boolean;
+}
+/**
+ * Interface for PDF processing services
+ */
+export declare abstract class IPdfService extends Service {
+    static readonly serviceType: "pdf";
+    readonly capabilityDescription = "PDF processing, extraction, and generation capabilities";
+    /**
+     * Extract text and metadata from a PDF file
+     * @param pdfPath - Path to the PDF file or buffer
+     * @returns Promise resolving to extracted text and metadata
+     */
+    abstract extractText(pdfPath: string | Buffer): Promise<PdfExtractionResult>;
+    /**
+     * Generate a PDF from HTML content
+     * @param htmlContent - HTML content to convert to PDF
+     * @param options - PDF generation options
+     * @returns Promise resolving to PDF buffer
+     */
+    abstract generatePdf(htmlContent: string, options?: PdfGenerationOptions): Promise<Buffer>;
+    /**
+     * Convert a document to PDF format
+     * @param filePath - Path to the document file
+     * @param options - Conversion options
+     * @returns Promise resolving to PDF buffer
+     */
+    abstract convertToPdf(filePath: string, options?: PdfConversionOptions): Promise<Buffer>;
+    /**
+     * Merge multiple PDF files into one
+     * @param pdfPaths - Array of PDF file paths or buffers
+     * @returns Promise resolving to merged PDF buffer
+     */
+    abstract mergePdfs(pdfPaths: (string | Buffer)[]): Promise<Buffer>;
+    /**
+     * Split a PDF into individual pages
+     * @param pdfPath - Path to the PDF file or buffer
+     * @returns Promise resolving to array of page buffers
+     */
+    abstract splitPdf(pdfPath: string | Buffer): Promise<Buffer[]>;
+}

package/dist/interfaces/post.d.ts

@@ -0,0 +1,240 @@
+import { Service, type UUID } from '@elizaos/core';
+export interface PostMedia {
+    id: UUID;
+    url: string;
+    type: 'image' | 'video' | 'audio' | 'document';
+    mimeType: string;
+    size: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+    thumbnail?: string;
+    description?: string;
+    altText?: string;
+}
+export interface PostLocation {
+    name: string;
+    address?: string;
+    coordinates?: {
+        latitude: number;
+        longitude: number;
+    };
+    placeId?: string;
+}
+export interface PostAuthor {
+    id: UUID;
+    username: string;
+    displayName: string;
+    avatar?: string;
+    verified?: boolean;
+    followerCount?: number;
+    followingCount?: number;
+    bio?: string;
+    website?: string;
+}
+export interface PostEngagement {
+    likes: number;
+    shares: number;
+    comments: number;
+    views?: number;
+    hasLiked: boolean;
+    hasShared: boolean;
+    hasCommented: boolean;
+    hasSaved: boolean;
+}
+export interface PostContent {
+    text?: string;
+    html?: string;
+    media?: PostMedia[];
+    location?: PostLocation;
+    tags?: string[];
+    mentions?: UUID[];
+    links?: Array<{
+        url: string;
+        title?: string;
+        description?: string;
+        image?: string;
+    }>;
+    poll?: {
+        question: string;
+        options: Array<{
+            text: string;
+            votes: number;
+        }>;
+        expiresAt?: Date;
+        multipleChoice?: boolean;
+    };
+}
+export interface PostInfo {
+    id: UUID;
+    author: PostAuthor;
+    content: PostContent;
+    platform: string;
+    platformId: string;
+    url: string;
+    createdAt: Date;
+    editedAt?: Date;
+    scheduledAt?: Date;
+    engagement: PostEngagement;
+    visibility: 'public' | 'private' | 'followers' | 'friends' | 'unlisted';
+    replyTo?: UUID;
+    thread?: {
+        id: UUID;
+        position: number;
+        total: number;
+    };
+    crossPosted?: Array<{
+        platform: string;
+        platformId: string;
+        url: string;
+    }>;
+}
+export interface PostCreateOptions {
+    platforms?: string[];
+    scheduledAt?: Date;
+    visibility?: PostInfo['visibility'];
+    replyTo?: UUID;
+    thread?: boolean;
+    location?: PostLocation;
+    tags?: string[];
+    mentions?: UUID[];
+    enableComments?: boolean;
+    enableSharing?: boolean;
+    contentWarning?: string;
+    sensitive?: boolean;
+}
+export interface PostSearchOptions {
+    query?: string;
+    author?: UUID;
+    platform?: string;
+    tags?: string[];
+    mentions?: UUID[];
+    since?: Date;
+    before?: Date;
+    limit?: number;
+    offset?: number;
+    hasMedia?: boolean;
+    hasLocation?: boolean;
+    visibility?: PostInfo['visibility'];
+    sortBy?: 'date' | 'engagement' | 'relevance';
+}
+export interface PostAnalytics {
+    postId: UUID;
+    platform: string;
+    impressions: number;
+    reach: number;
+    engagement: PostEngagement;
+    clicks: number;
+    shares: number;
+    saves: number;
+    demographics?: {
+        age?: Record<string, number>;
+        gender?: Record<string, number>;
+        location?: Record<string, number>;
+    };
+    topPerformingHours?: Array<{
+        hour: number;
+        engagement: number;
+    }>;
+}
+/**
+ * Interface for social media posting services
+ */
+export declare abstract class IPostService extends Service {
+    static readonly serviceType: "post";
+    readonly capabilityDescription = "Social media posting and content management capabilities";
+    /**
+     * Create and publish a new post
+     * @param content - Post content
+     * @param options - Publishing options
+     * @returns Promise resolving to post ID
+     */
+    abstract createPost(content: PostContent, options?: PostCreateOptions): Promise<UUID>;
+    /**
+     * Get posts from timeline or specific user
+     * @param options - Search options
+     * @returns Promise resolving to array of posts
+     */
+    abstract getPosts(options?: PostSearchOptions): Promise<PostInfo[]>;
+    /**
+     * Get a specific post by ID
+     * @param postId - Post ID
+     * @returns Promise resolving to post info
+     */
+    abstract getPost(postId: UUID): Promise<PostInfo>;
+    /**
+     * Edit an existing post
+     * @param postId - Post ID
+     * @param content - New post content
+     * @returns Promise resolving when edit completes
+     */
+    abstract editPost(postId: UUID, content: PostContent): Promise<void>;
+    /**
+     * Delete a post
+     * @param postId - Post ID
+     * @returns Promise resolving when deletion completes
+     */
+    abstract deletePost(postId: UUID): Promise<void>;
+    /**
+     * Like/unlike a post
+     * @param postId - Post ID
+     * @param like - True to like, false to unlike
+     * @returns Promise resolving when operation completes
+     */
+    abstract likePost(postId: UUID, like: boolean): Promise<void>;
+    /**
+     * Share/repost a post
+     * @param postId - Post ID
+     * @param comment - Optional comment when sharing
+     * @returns Promise resolving to share ID
+     */
+    abstract sharePost(postId: UUID, comment?: string): Promise<UUID>;
+    /**
+     * Save/unsave a post
+     * @param postId - Post ID
+     * @param save - True to save, false to unsave
+     * @returns Promise resolving when operation completes
+     */
+    abstract savePost(postId: UUID, save: boolean): Promise<void>;
+    /**
+     * Comment on a post
+     * @param postId - Post ID
+     * @param content - Comment content
+     * @returns Promise resolving to comment ID
+     */
+    abstract commentOnPost(postId: UUID, content: PostContent): Promise<UUID>;
+    /**
+     * Get comments for a post
+     * @param postId - Post ID
+     * @param options - Search options
+     * @returns Promise resolving to array of comments
+     */
+    abstract getComments(postId: UUID, options?: PostSearchOptions): Promise<PostInfo[]>;
+    /**
+     * Schedule a post for later publishing
+     * @param content - Post content
+     * @param scheduledAt - When to publish
+     * @param options - Publishing options
+     * @returns Promise resolving to scheduled post ID
+     */
+    abstract schedulePost(content: PostContent, scheduledAt: Date, options?: PostCreateOptions): Promise<UUID>;
+    /**
+     * Get analytics for a post
+     * @param postId - Post ID
+     * @returns Promise resolving to post analytics
+     */
+    abstract getPostAnalytics(postId: UUID): Promise<PostAnalytics>;
+    /**
+     * Get trending posts
+     * @param options - Search options
+     * @returns Promise resolving to trending posts
+     */
+    abstract getTrendingPosts(options?: PostSearchOptions): Promise<PostInfo[]>;
+    /**
+     * Search posts across platforms
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Promise resolving to search results
+     */
+    abstract searchPosts(query: string, options?: PostSearchOptions): Promise<PostInfo[]>;
+}

package/dist/interfaces/token.d.ts

@@ -0,0 +1,72 @@
+import { Service } from '@elizaos/core';
+/**
+ * A standardized representation of a token holding.
+ */
+export interface TokenBalance {
+    address: string;
+    balance: string;
+    decimals: number;
+    uiAmount?: number;
+    name?: string;
+    symbol?: string;
+    logoURI?: string;
+}
+/**
+ * Generic representation of token data that can be provided by various services.
+ */
+export interface TokenData {
+    id: string;
+    symbol: string;
+    name: string;
+    address: string;
+    chain: string;
+    sourceProvider: string;
+    price?: number;
+    priceChange24hPercent?: number;
+    priceChange24hUSD?: number;
+    volume24hUSD?: number;
+    marketCapUSD?: number;
+    liquidity?: number;
+    holders?: number;
+    logoURI?: string;
+    decimals?: number;
+    lastUpdatedAt?: Date;
+    raw?: any;
+}
+/**
+ * Interface for a generic service that provides token data.
+ */
+export declare abstract class ITokenDataService extends Service {
+    static readonly serviceType: "token_data";
+    readonly capabilityDescription: string;
+    /**
+     * Fetches detailed information for a single token.
+     * @param address The token's contract address.
+     * @param chain The blockchain the token resides on.
+     * @returns A Promise resolving to TokenData or null if not found.
+     */
+    abstract getTokenDetails(address: string, chain: string): Promise<TokenData | null>;
+    /**
+     * Fetches a list of trending tokens.
+     * @param chain Optional: Filter by a specific blockchain.
+     * @param limit Optional: Number of tokens to return. Defaults to a service-specific value.
+     * @param timePeriod Optional: Time period for trending data (e.g., '24h', '7d'). Defaults to service-specific.
+     * @returns A Promise resolving to an array of TokenData.
+     */
+    abstract getTrendingTokens(chain?: string, limit?: number, timePeriod?: string): Promise<TokenData[]>;
+    /**
+     * Searches for tokens based on a query string.
+     * @param query The search query (e.g., symbol, name, address).
+     * @param chain Optional: Filter by a specific blockchain.
+     * @param limit Optional: Number of results to return.
+     * @returns A Promise resolving to an array of TokenData.
+     */
+    abstract searchTokens(query: string, chain?: string, limit?: number): Promise<TokenData[]>;
+    /**
+     * Fetches data for multiple tokens by their addresses on a specific chain.
+     * @param addresses Array of token contract addresses.
+     * @param chain The blockchain the tokens reside on.
+     * @returns A Promise resolving to an array of TokenData. May not include all requested if some are not found.
+     */
+    abstract getTokensByAddresses(addresses: string[], chain: string): Promise<TokenData[]>;
+}

package/dist/interfaces/transcription.d.ts

@@ -0,0 +1,107 @@
+import { Service } from '@elizaos/core';
+export interface TranscriptionOptions {
+    language?: string;
+    model?: string;
+    temperature?: number;
+    prompt?: string;
+    response_format?: 'json' | 'text' | 'srt' | 'vtt' | 'verbose_json';
+    timestamp_granularities?: ('word' | 'segment')[];
+    word_timestamps?: boolean;
+    segment_timestamps?: boolean;
+}
+export interface TranscriptionResult {
+    text: string;
+    language?: string;
+    duration?: number;
+    segments?: TranscriptionSegment[];
+    words?: TranscriptionWord[];
+    confidence?: number;
+}
+export interface TranscriptionSegment {
+    id: number;
+    text: string;
+    start: number;
+    end: number;
+    confidence?: number;
+    tokens?: number[];
+    temperature?: number;
+    avg_logprob?: number;
+    compression_ratio?: number;
+    no_speech_prob?: number;
+}
+export interface TranscriptionWord {
+    word: string;
+    start: number;
+    end: number;
+    confidence?: number;
+}
+export interface SpeechToTextOptions {
+    language?: string;
+    model?: string;
+    continuous?: boolean;
+    interimResults?: boolean;
+    maxAlternatives?: number;
+}
+export interface TextToSpeechOptions {
+    voice?: string;
+    model?: string;
+    speed?: number;
+    format?: 'mp3' | 'wav' | 'flac' | 'aac';
+    response_format?: 'mp3' | 'opus' | 'aac' | 'flac';
+}
+/**
+ * Interface for audio transcription and speech services
+ */
+export declare abstract class ITranscriptionService extends Service {
+    static readonly serviceType: "transcription";
+    readonly capabilityDescription = "Audio transcription and speech processing capabilities";
+    /**
+     * Transcribe audio file to text
+     * @param audioPath - Path to audio file or audio buffer
+     * @param options - Transcription options
+     * @returns Promise resolving to transcription result
+     */
+    abstract transcribeAudio(audioPath: string | Buffer, options?: TranscriptionOptions): Promise<TranscriptionResult>;
+    /**
+     * Transcribe video file to text (extracts audio first)
+     * @param videoPath - Path to video file or video buffer
+     * @param options - Transcription options
+     * @returns Promise resolving to transcription result
+     */
+    abstract transcribeVideo(videoPath: string | Buffer, options?: TranscriptionOptions): Promise<TranscriptionResult>;
+    /**
+     * Real-time speech to text from audio stream
+     * @param audioStream - Audio stream or buffer
+     * @param options - Speech to text options
+     * @returns Promise resolving to transcription result
+     */
+    abstract speechToText(audioStream: NodeJS.ReadableStream | Buffer, options?: SpeechToTextOptions): Promise<TranscriptionResult>;
+    /**
+     * Convert text to speech
+     * @param text - Text to convert to speech
+     * @param options - Text to speech options
+     * @returns Promise resolving to audio buffer
+     */
+    abstract textToSpeech(text: string, options?: TextToSpeechOptions): Promise<Buffer>;
+    /**
+     * Get supported languages for transcription
+     * @returns Promise resolving to array of supported language codes
+     */
+    abstract getSupportedLanguages(): Promise<string[]>;
+    /**
+     * Get available voices for text to speech
+     * @returns Promise resolving to array of available voices
+     */
+    abstract getAvailableVoices(): Promise<Array<{
+        id: string;
+        name: string;
+        language: string;
+        gender?: 'male' | 'female' | 'neutral';
+    }>>;
+    /**
+     * Detect language of audio file
+     * @param audioPath - Path to audio file or audio buffer
+     * @returns Promise resolving to detected language code
+     */
+    abstract detectLanguage(audioPath: string | Buffer): Promise<string>;
+}