> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Developing Extensions

> Create custom extensions for EnConvo

## 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.

<Card title="Extension Repository" icon="github" href="https://github.com/enconvo">
  All official extensions are open source on GitHub
</Card>

## 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

<Steps>
  <Step title="Initialize Project">
    ```bash theme={null}
    npx create-enconvo-extension my-extension
    cd my-extension
    npm install
    ```
  </Step>

  <Step title="Configure Metadata">
    Edit `package.json`:

    ```json theme={null}
    {
      "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"
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Write Command Handler">
    Edit `src/index.ts`:

    ```typescript theme={null}
    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'}!`;
      }
    }
    ```
  </Step>

  <Step title="Build and Test">
    ```bash theme={null}
    npm run build
    npm run dev  # Hot reload during development
    ```
  </Step>

  <Step title="Install Locally">
    Settings → Extensions → Install from Folder → Select your extension
  </Step>
</Steps>

## Extension API

### Core APIs

```typescript theme={null}
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

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

### Storage APIs

```typescript theme={null}
import {
  LocalStorage,     // Persistent local storage
  SecureStorage,    // Encrypted storage for API keys
} from '@enconvo/storage';
```

### UI APIs

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

<AccordionGroup>
  <Accordion title="Handle errors gracefully">
    ```typescript theme={null}
    try {
      const result = await riskyOperation();
      return result;
    } catch (error) {
      showToast({ title: 'Error', message: error.message, style: 'failure' });
      return 'An error occurred';
    }
    ```
  </Accordion>

  <Accordion title="Show progress for long operations">
    ```typescript theme={null}
    import { showLoading, hideLoading } from '@enconvo/api';

    showLoading('Processing...');
    const result = await longOperation();
    hideLoading();
    ```
  </Accordion>

  <Accordion title="Use secure storage for API keys">
    ```typescript theme={null}
    import { SecureStorage } from '@enconvo/storage';

    const apiKey = await SecureStorage.get('api-key');
    ```
  </Accordion>

  <Accordion title="Provide good documentation">
    Include clear README with usage examples and configuration instructions.
  </Accordion>
</AccordionGroup>

## Publishing Extensions

### Prepare for Publication

1. Update version in `package.json`
2. Write comprehensive README
3. Add screenshots/GIFs
4. Test thoroughly

### Submit to Store

1. Create GitHub repository
2. Open issue in [enconvo/extensions](https://github.com/enconvo/extensions)
3. Follow submission template
4. Wait for review

### Share Directly

Share your extension via:

* GitHub repository link
* Direct .zip file
* npm package

## Debugging

### Development Mode

Run with hot reload:

```bash theme={null}
npm run dev
```

### Console Logging

```typescript theme={null}
console.log('Debug info:', data);
// View in EnConvo → Debug → Console
```

### Extension Logs

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

## Resources

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="https://github.com/enconvo/api">
    Complete API documentation
  </Card>

  <Card title="Example Extensions" icon="code" href="https://github.com/enconvo">
    Browse official extensions for examples
  </Card>
</CardGroup>