@pompeii-labs/pompeii/dist/index.d.mts

The Pompeii Platform SDK from Pompeii Labs

import { MagmaMessageType, MagmaMessage } from '@pompeii-labs/magma/types';

type NotificationInsert = {
    name: string;
    payload: NotificationPayload;
    session_id?: string;
    user_id?: string;
};
/**
 * Represents a clickable link in a notification
 * @example
 * ```typescript
 * const link: NotificationLink = {
 *   type: 'link',
 *   label: 'View Details',
 *   url: 'https://example.com/details'
 * }
 * ```
 */
type NotificationLink = {
    type: 'link';
    /** The text to display for the link */
    label: string;
    /** The URL the link should navigate to */
    url: string;
};
/**
 * Represents an interactive button in a notification
 * @example
 * ```typescript
 * const button: NotificationButton = {
 *   type: 'button',
 *   label: 'Approve',
 *   action_id: 'approve_request',
 *   value: { requestId: '123', userId: 'abc' }
 * }
 * ```
 */
type NotificationButton = {
    type: 'button';
    /** The text to display on the button */
    label: string;
    /** Unique identifier for the action this button triggers */
    action_id: string;
    /** Metadata passed to the agent handling this action (not visible to user) */
    value?: Record<string, unknown>;
};
/**
 * Represents an input field in a notification
 * @example
 * ```typescript
 * const input: NotificationInput = {
 *   type: 'input',
 *   label: 'Enter your response',
 *   action_id: 'user_response',
 *   value: { context: 'approval_flow', stepId: 2 }
 * }
 * ```
 */
type NotificationInput = {
    type: 'input';
    /** The label/placeholder text for the input field */
    label: string;
    /** Unique identifier for the action this input triggers */
    action_id: string;
    /** Metadata passed to the agent handling this action (not visible to user) */
    value?: Record<string, unknown>;
};
type NotificationAction = NotificationLink | NotificationButton | NotificationInput;
type NotificationPayload = {
    type: 'info' | 'error' | 'warning' | 'success';
    description: string;
    actions?: NotificationAction[];
};

type EventInsert = {
    name: string;
    type: string;
    payload: Record<string, unknown>;
    session_id?: string;
    user_id?: string;
};

type AgentStatus = 'draft' | 'deploying' | 'deployed' | 'building' | 'error' | 'archived' | 'idle';
type ACPAgentType = {
    id: string;
    name: string;
    status: AgentStatus;
    endpoint?: string;
    templateId?: number;
    summary?: string;
};
type ACPChatRequest = {
    /** Message history to send to the agent */
    messages: MagmaMessageType[];
    /** Session ID to continue a conversation (optional) */
    sessionId?: string;
    /** Data to populate for agent.state fields (optional) */
    state?: Record<string, any>;
    /** Data to pass to agent.setup (optional) - this will be passed to the agent.setup function */
    setup?: Record<string, any>;
    /** Callback for streamed SSE data */
    cb?: (data: Record<string, any>) => void;
};

/**
 * ACP Agent class
 * ACP representation of a Magma agent that can be used to send chat requests to the agent
 */
declare class ACPAgent implements ACPAgentType {
    id: string;
    name: string;
    status: AgentStatus;
    endpoint?: string;
    templateId?: number;
    summary?: string;
    private readonly apiKey;
    constructor(acpAgent: ACPAgentType & {
        apiKey: string;
    });
    /**
     * Send a chat request to the ACP agent
     *
     * @param request The chat request to send to the ACP agent
     * @param onChunk Optional callback function for streaming SSE data
     * @returns The response message from the ACP agent
     */
    chat(request: ACPChatRequest): Promise<MagmaMessage>;
    /**
     * Handle Server-Sent Events response stream
     *
     * @param response The fetch response object
     * @param onChunk Optional callback for each data chunk
     * @returns The final message result
     */
    private handleSSEResponse;
    request(path: string, options: RequestInit, cb?: (data: any) => void): Promise<Record<string, any>>;
}

type InferenceAgent = {
    name: string;
    description: string;
    version: string;
};
type InferenceRequest = {
    agent: string;
    messages: MagmaMessageType[];
    setup?: Record<string, any>;
    state?: Record<string, any>;
    cb?: (data: Record<string, any>) => void;
};

/**
 * Inference API client
 *
 * Magma provides an inference API that allows you to interact with built-in official Magma agents
 */
declare class Inference {
    private readonly apiKey;
    constructor(apiKey: string);
    /**
     * List all inference agents
     *
     * @returns list of inference agents
     */
    list(): Promise<InferenceAgent[]>;
    run(request: InferenceRequest): Promise<MagmaMessage>;
    /**
     * Handle Server-Sent Events response stream
     *
     * @param response The fetch response object
     * @param onChunk Optional callback for each data chunk
     * @returns The final message result
     */
    private handleSSEResponse;
}

declare class Pompeii {
    private readonly apiKey;
    inference: Inference;
    constructor(apiKey?: string);
    /**
     * Make a request to the Pompeii Platform API
     *
     * @param route The route to make the request to
     * @param args The arguments to pass to the request
     * @returns The response from the request
     */
    private request;
    /**
     * List all available ACP agents
     *
     * @returns A list of ACP agents
     * @throws Error if the request fails
     */
    acp(): Promise<ACPAgent[]>;
    /**
     * Post a notification to the Pompeii Platform. This will be displayed to applicable users on their home page.
     *
     * @param notification The notification to post
     * @returns void
     * @throws Error if the request fails
     */
    notify(notification: NotificationInsert): Promise<void>;
    /**
     * Post an event to the Pompeii Platform. This will be displayed in the Agent's Observability tab.
     *
     * @param event The event to post
     * @returns void
     * @throws Error if the request fails
     */
    event(event: EventInsert): Promise<void>;
    downloadFiles(targetDir: string, paths?: string[]): Promise<string[]>;
    private downloadFile;
}

export { ACPAgent, type ACPAgentType, type ACPChatRequest, type AgentStatus, type EventInsert, type InferenceAgent, type InferenceRequest, type NotificationAction, type NotificationButton, type NotificationInput, type NotificationInsert, type NotificationLink, type NotificationPayload, Pompeii };