@artyfacts/openclaw 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,446 @@
+/**
+ * Device authentication flow for Artyfacts OpenClaw adapter
+ *
+ * Implements device auth flow:
+ * 1. Request device code from Artyfacts
+ * 2. Display code for user to enter on website
+ * 3. Poll for completion
+ * 4. Store credentials locally
+ */
+interface Credentials {
+    apiKey: string;
+    agentId: string;
+    agentName?: string;
+    expiresAt?: string;
+}
+/**
+ * Load stored credentials from disk
+ */
+declare function loadCredentials(): Credentials | null;
+/**
+ * Save credentials to disk
+ */
+declare function saveCredentials(credentials: Credentials): void;
+/**
+ * Clear stored credentials
+ */
+declare function clearCredentials(): void;
+/**
+ * Prompt user for manual API key entry
+ */
+declare function promptForApiKey(): Promise<Credentials>;
+/**
+ * Get credentials, running auth flow if needed
+ */
+declare function getCredentials(options?: {
+    baseUrl?: string;
+    forceAuth?: boolean;
+}): Promise<Credentials>;
+
+/**
+ * OpenClaw executor for Artyfacts tasks
+ *
+ * Executes tasks by shelling out to the OpenClaw CLI.
+ * Uses the user's existing OpenClaw Gateway - no separate API key needed.
+ *
+ * Supports fetching full context (organization, project, artifact, related sections)
+ * to provide OpenClaw with the information needed to complete tasks effectively.
+ */
+interface TaskContext {
+    /** Task ID (section ID) */
+    taskId: string;
+    /** Task heading/title */
+    heading: string;
+    /** Task content/description */
+    content: string;
+    /** Parent artifact ID */
+    artifactId: string;
+    /** Parent artifact title */
+    artifactTitle?: string;
+    /** Task priority (1=high, 2=medium, 3=low) */
+    priority?: number;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+interface ExecutionResult {
+    /** Whether execution was successful */
+    success: boolean;
+    /** The generated output */
+    output: string;
+    /** Summary of what was accomplished */
+    summary: string;
+    /** Any error message if failed */
+    error?: string;
+    /** The prompt that was used (for debugging) */
+    promptUsed?: string;
+}
+interface ExecutorConfig {
+    /** Path to openclaw CLI (default: 'openclaw') */
+    openclawPath?: string;
+    /** Timeout in milliseconds (default: 5 minutes) */
+    timeout?: number;
+    /** System prompt prefix */
+    systemPromptPrefix?: string;
+    /** Artyfacts API base URL (for fetching context) */
+    baseUrl?: string;
+    /** Artyfacts API key (for fetching context) */
+    apiKey?: string;
+    /** Whether to use full context from API (default: true if apiKey provided) */
+    useFullContext?: boolean;
+    /** OpenClaw session key to use (optional) */
+    sessionKey?: string;
+}
+declare class OpenClawExecutor {
+    private config;
+    private contextFetcher;
+    constructor(config?: ExecutorConfig);
+    /**
+     * Check if OpenClaw CLI is installed
+     */
+    isInstalled(): Promise<boolean>;
+    /**
+     * Get OpenClaw version
+     */
+    getVersion(): Promise<string | null>;
+    /**
+     * Execute a task using OpenClaw CLI
+     */
+    execute(task: TaskContext): Promise<ExecutionResult>;
+    /**
+     * Run OpenClaw CLI with the given prompt
+     */
+    private runOpenClaw;
+    /**
+     * Build the task prompt
+     */
+    private buildTaskPrompt;
+    /**
+     * Parse the response to extract content and summary
+     */
+    private parseResponse;
+}
+declare function createExecutor(config?: ExecutorConfig): OpenClawExecutor;
+
+/**
+ * SSE Event Listener for Artyfacts task assignments
+ *
+ * Connects to the Artyfacts SSE stream and listens for task_assigned events.
+ * Uses EventSource for automatic reconnection handling.
+ */
+interface TaskAssignedEvent {
+    type: 'task_assigned';
+    timestamp: string;
+    data: {
+        taskId: string;
+        sectionId: string;
+        heading: string;
+        content: string;
+        artifactId: string;
+        artifactTitle?: string;
+        priority?: number;
+        assignedTo: string;
+        assignedAt: string;
+    };
+}
+interface McpConnectRequestEvent {
+    type: 'mcp_connect_request';
+    timestamp: string;
+    data: {
+        connection_id: string;
+        platform: string;
+        config: {
+            server_name?: string;
+            connection_string?: string;
+            api_key?: string;
+            [key: string]: unknown;
+        };
+    };
+}
+interface HeartbeatEvent {
+    type: 'heartbeat';
+    timestamp: string;
+}
+interface ConnectedEvent {
+    type: 'connected';
+    timestamp: string;
+    data: {
+        agentId: string;
+    };
+}
+type ArtyfactsEvent = TaskAssignedEvent | HeartbeatEvent | ConnectedEvent | McpConnectRequestEvent | {
+    type: string;
+    timestamp: string;
+    data?: Record<string, unknown>;
+};
+type EventCallback<T extends ArtyfactsEvent = ArtyfactsEvent> = (event: T) => void | Promise<void>;
+interface ListenerConfig {
+    /** Artyfacts API key */
+    apiKey: string;
+    /** Agent ID to listen for */
+    agentId: string;
+    /** Base URL for Artyfacts API */
+    baseUrl?: string;
+    /** Callback for state changes */
+    onStateChange?: (state: ConnectionState) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+declare class ArtyfactsListener {
+    private config;
+    private eventSource;
+    private callbacks;
+    private allCallbacks;
+    private state;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    constructor(config: ListenerConfig);
+    /**
+     * Get current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Subscribe to all events
+     */
+    subscribe(callback: EventCallback): () => void;
+    /**
+     * Subscribe to a specific event type
+     */
+    on<T extends ArtyfactsEvent>(type: string, callback: EventCallback<T>): () => void;
+    /**
+     * Connect to the SSE stream
+     */
+    connect(): void;
+    /**
+     * Disconnect from the SSE stream
+     */
+    disconnect(): void;
+    /**
+     * Reconnect to the SSE stream
+     */
+    reconnect(): void;
+    /**
+     * Handle incoming SSE message
+     */
+    private handleMessage;
+    /**
+     * Safely call a callback, handling async and errors
+     */
+    private safeCallCallback;
+    /**
+     * Handle SSE error
+     */
+    private handleError;
+    /**
+     * Update connection state
+     */
+    private setState;
+}
+/**
+ * Create an Artyfacts event listener
+ */
+declare function createListener(config: ListenerConfig): ArtyfactsListener;
+
+/**
+ * Context fetcher for Artyfacts tasks
+ *
+ * Fetches full context including organization, project, artifact, and related sections.
+ */
+interface OrganizationContext {
+    id: string;
+    name: string;
+    context?: string;
+}
+interface ProjectContext {
+    id: string;
+    name: string;
+    description?: string;
+}
+interface SectionContext {
+    id: string;
+    heading: string;
+    content?: string;
+    section_type?: string;
+    task_status?: string;
+}
+interface ArtifactContext {
+    id: string;
+    title: string;
+    summary?: string;
+    description?: string;
+    artifact_type?: string;
+    sections: SectionContext[];
+}
+interface TaskFullContext {
+    task: {
+        id: string;
+        heading: string;
+        content: string;
+        expected_output?: {
+            format?: string;
+            requirements?: string[];
+        };
+        priority?: number;
+    };
+    artifact: ArtifactContext;
+    project?: ProjectContext;
+    organization: OrganizationContext;
+}
+interface ContextFetcherConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+declare class ContextFetcher {
+    private config;
+    constructor(config: ContextFetcherConfig);
+    /**
+     * Fetch full context for a task
+     */
+    fetchTaskContext(taskId: string): Promise<TaskFullContext>;
+}
+/**
+ * Build a rich prompt with full context
+ */
+declare function buildPromptWithContext(context: TaskFullContext): string;
+declare function createContextFetcher(config: ContextFetcherConfig): ContextFetcher;
+
+/**
+ * MCP connection handler for OpenClaw
+ *
+ * Manages the configuration of Artyfacts MCP server in OpenClaw.
+ * OpenClaw uses `openclaw mcp set/unset` for MCP server management.
+ */
+interface McpConfig {
+    /** Name for the MCP server entry */
+    name?: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for Artyfacts API */
+    baseUrl?: string;
+    /** Path to openclaw CLI */
+    openclawPath?: string;
+}
+interface McpStatus {
+    /** Whether MCP is configured */
+    configured: boolean;
+    /** Name of the configured server */
+    name?: string;
+    /** Any error message */
+    error?: string;
+}
+declare class McpHandler {
+    private config;
+    private openclawPath;
+    constructor(config: McpConfig);
+    /**
+     * Check if Artyfacts MCP server is already configured
+     */
+    isConfigured(): McpStatus;
+    /**
+     * Configure Artyfacts MCP server in OpenClaw
+     *
+     * Uses: openclaw mcp set <name> --command "npx" --args "-y @artyfacts/mcp-server"
+     */
+    configure(): boolean;
+    /**
+     * Alternative configuration approach using JSON config
+     */
+    private configureAlternative;
+    /**
+     * Print manual configuration instructions
+     */
+    private printManualInstructions;
+    /**
+     * Remove Artyfacts MCP configuration
+     */
+    remove(): boolean;
+    /**
+     * Ensure MCP is configured, configure if needed
+     */
+    ensureConfigured(): boolean;
+}
+declare function createMcpHandler(config: McpConfig): McpHandler;
+
+/**
+ * Introspect OpenClaw local configuration
+ * Reads config files and returns structured data for Artyfacts import
+ */
+interface CronJob {
+    jobId: string;
+    name?: string;
+    schedule: {
+        kind: 'at' | 'every' | 'cron';
+        at?: string;
+        every?: number;
+        cron?: string;
+        timezone?: string;
+    };
+    payload: {
+        kind: 'systemEvent' | 'agentTurn';
+        message?: string;
+    };
+    delivery?: {
+        mode: 'none' | 'announce' | 'webhook';
+        channel?: string;
+        to?: string;
+    };
+    enabled?: boolean;
+}
+interface HeartbeatConfig {
+    every?: string;
+    model?: string;
+    prompt?: string;
+    target?: string;
+    to?: string;
+    lightContext?: boolean;
+    isolatedSession?: boolean;
+    activeHours?: {
+        start: string;
+        end: string;
+    };
+}
+interface AgentConfig {
+    id: string;
+    name?: string;
+    default?: boolean;
+    heartbeat?: HeartbeatConfig;
+    model?: string;
+    systemPrompt?: string;
+}
+interface McpServer {
+    name: string;
+    command?: string;
+    args?: string[];
+    url?: string;
+    transport?: 'stdio' | 'http' | 'sse';
+    env?: Record<string, string>;
+}
+interface Skill {
+    name: string;
+    path: string;
+    description?: string;
+    content?: string;
+}
+interface OpenClawConfig {
+    crons: CronJob[];
+    heartbeat: HeartbeatConfig | null;
+    agents: AgentConfig[];
+    mcpServers: McpServer[];
+    skills: Skill[];
+    channels: string[];
+}
+/**
+ * Introspect all OpenClaw configuration
+ */
+declare function introspect(): Promise<OpenClawConfig>;
+/**
+ * Get a summary of the configuration for display
+ */
+declare function summarize(config: OpenClawConfig): string;
+
+export { type AgentConfig, ArtyfactsListener, ContextFetcher, type Credentials, type CronJob, type ExecutionResult, type ExecutorConfig, type HeartbeatConfig, type ListenerConfig, type McpConfig, type McpConnectRequestEvent, McpHandler, type McpServer, type McpStatus, type OpenClawConfig, OpenClawExecutor, type Skill, type TaskAssignedEvent, type TaskContext, type TaskFullContext, buildPromptWithContext, clearCredentials, createContextFetcher, createExecutor, createListener, createMcpHandler, getCredentials, introspect, loadCredentials, promptForApiKey, saveCredentials, summarize };