Developing Extensions

Overview

EnConvo’s extension system is fully open source, allowing you to create custom extensions tailored to your needs. Extensions are built with TypeScript/JavaScript and can access EnConvo’s powerful APIs.

Extension Repository

All official extensions are open source on GitHub

Getting Started

Prerequisites

Node.js 18+ installed
Basic TypeScript/JavaScript knowledge
EnConvo installed on your Mac

Extension Structure

my-extension/
├── package.json       # Extension metadata
├── src/
│   ├── index.ts      # Entry point
│   └── commands/     # Command handlers
├── assets/           # Icons and images
└── README.md         # Documentation

Creating Your First Extension

Initialize Project

npx create-enconvo-extension my-extension
cd my-extension
npm install

Configure Metadata

Edit package.json:

{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "My custom EnConvo extension",
  "version": "1.0.0",
  "enconvo": {
    "commands": [
      {
        "name": "hello",
        "title": "Say Hello",
        "description": "A simple hello command"
      }
    ]
  }
}

Write Command Handler

Edit src/index.ts:

import { Command, showToast } from '@enconvo/api';

export default class HelloCommand implements Command {
  async run(input: string): Promise<string> {
    showToast({ title: 'Hello!', message: input });
    return `Hello, ${input || 'World'}!`;
  }
}

Build and Test

npm run build
npm run dev  # Hot reload during development

Install Locally

Settings → Extensions → Install from Folder → Select your extension

Extension API

Core APIs

import {
  Command,          // Base command class
  showToast,        // Show notification
  showHUD,          // Show heads-up display
  getInput,         // Get user input
  getSelection,     // Get selected text
  setClipboard,     // Set clipboard content
  getClipboard,     // Get clipboard content
  openURL,          // Open URL in browser
  runAppleScript,   // Run AppleScript
} from '@enconvo/api';

AI APIs

import {
  chat,             // Send chat message to AI
  complete,         // Get completion
  embed,            // Get text embeddings
  generateImage,    // Generate image
} from '@enconvo/ai';

Storage APIs

import {
  LocalStorage,     // Persistent local storage
  SecureStorage,    // Encrypted storage for API keys
} from '@enconvo/storage';

UI APIs

import {
  Form,             // Form UI components
  List,             // List UI components
  Detail,           // Detail view
  Action,           // Actions/buttons
} from '@enconvo/ui';

Command Types

Simple Command

Returns text output:

export default class SimpleCommand implements Command {
  async run(input: string): Promise<string> {
    // Process input and return result
    return `Processed: ${input}`;
  }
}

Form Command

Shows a form for input:

import { Form, FormCommand } from '@enconvo/api';

export default class FormCommand implements FormCommand {
  async getForm(): Promise<Form> {
    return {
      fields: [
        { name: 'topic', type: 'text', label: 'Topic' },
        { name: 'length', type: 'dropdown', options: ['short', 'medium', 'long'] }
      ]
    };
  }
  
  async run(values: Record<string, any>): Promise<string> {
    return `Writing about ${values.topic} (${values.length})`;
  }
}

List Command

Shows a selectable list:

import { List, ListCommand } from '@enconvo/api';

export default class ListCommand implements ListCommand {
  async getItems(query: string): Promise<ListItem[]> {
    return [
      { title: 'Item 1', subtitle: 'Description', value: '1' },
      { title: 'Item 2', subtitle: 'Description', value: '2' }
    ];
  }
  
  async onSelect(item: ListItem): Promise<string> {
    return `Selected: ${item.value}`;
  }
}

Using AI in Extensions

import { chat, ChatMessage } from '@enconvo/ai';

export default class AICommand implements Command {
  async run(input: string): Promise<string> {
    const messages: ChatMessage[] = [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: input }
    ];
    
    const response = await chat({
      messages,
      model: 'gpt-4',
      temperature: 0.7
    });
    
    return response.content;
  }
}

Best Practices

Handle errors gracefully

try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  showToast({ title: 'Error', message: error.message, style: 'failure' });
  return 'An error occurred';
}

Show progress for long operations

import { showLoading, hideLoading } from '@enconvo/api';

showLoading('Processing...');
const result = await longOperation();
hideLoading();

Use secure storage for API keys

import { SecureStorage } from '@enconvo/storage';

const apiKey = await SecureStorage.get('api-key');

Provide good documentation

Include clear README with usage examples and configuration instructions.

Publishing Extensions

Prepare for Publication

Update version in package.json
Write comprehensive README
Add screenshots/GIFs
Test thoroughly

Submit to Store

Create GitHub repository
Open issue in enconvo/extensions
Follow submission template
Wait for review

Share your extension via:

GitHub repository link
Direct .zip file
npm package

Debugging

Development Mode

Run with hot reload:

npm run dev

Console Logging

console.log('Debug info:', data);
// View in EnConvo → Debug → Console

Extension Logs

View logs: Settings → Extensions → [Extension] → View Logs

Resources

API Reference

Complete API documentation

Example Extensions

Browse official extensions for examples

Getting Started

Core Features

AI Capabilities

Providers

Workflows & Extensions

Integrations

Advanced

Configuration

Resources

Overview

Extension Repository

Getting Started

Prerequisites

Extension Structure

Creating Your First Extension

Extension API

Core APIs

AI APIs

Storage APIs

UI APIs

Command Types

Simple Command

Form Command

List Command

Using AI in Extensions

Best Practices

Publishing Extensions

Prepare for Publication

Submit to Store

Debugging

Development Mode

Console Logging

Extension Logs

Resources

API Reference

Example Extensions

​Overview

Extension Repository

​Getting Started

​Prerequisites

​Extension Structure

​Creating Your First Extension

​Extension API

​Core APIs

​AI APIs

​Storage APIs

​UI APIs

​Command Types

​Simple Command

​Form Command

​List Command

​Using AI in Extensions

​Best Practices

​Publishing Extensions

​Prepare for Publication

​Submit to Store

​Share Directly

​Debugging

​Development Mode

​Console Logging

​Extension Logs

​Resources

API Reference

Example Extensions

Overview

Getting Started

Prerequisites

Extension Structure

Creating Your First Extension

Extension API

Core APIs

AI APIs

Storage APIs

UI APIs

Command Types

Simple Command

Form Command

List Command

Using AI in Extensions

Best Practices

Publishing Extensions

Prepare for Publication

Submit to Store

Share Directly

Debugging

Development Mode

Console Logging

Extension Logs

Resources