# Plugin API

Windshift exposes host functions that plugins can call to interact with the platform. These are available to all WASM plugins through the Extism host function interface.

## Logging

### `log`

Write a message to the Windshift server log.

**Parameters:**
- `level` - Log level: `debug`, `info`, `warn`, `error`
- `message` - The log message

**Example:**

```
log("info", "Processing webhook payload")
log("error", "Failed to parse response")
```

## HTTP

### `http_fetch`

Make an HTTP request to an external service.

**Parameters:**
- `url` - The request URL
- `method` - HTTP method (GET, POST, PUT, DELETE, etc.)
- `headers` - Request headers (JSON object)
- `body` - Request body (string)
- `timeout` - Request timeout in seconds

**Returns:** Response body as a string

**Example:**

```json
{
  "url": "https://api.example.com/webhook",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer token123"
  },
  "body": "{\"event\": \"task.completed\"}",
  "timeout": 10
}
```

## Email

### `smtp_send`

Send an email through the configured SMTP server.

**Parameters:**
- `to` - Recipient email addresses
- `subject` - Email subject
- `body` - Email body (HTML or plain text)

The SMTP connection uses the server-level SMTP configuration. Plugins don't need to provide SMTP credentials.

## Key-Value Storage

Persistent storage scoped to each plugin. Data survives server restarts.

### `kv_get`

Retrieve a value by key.

**Parameters:**
- `key` - The storage key

**Returns:** The stored value, or empty if not found

### `kv_set`

Store a value.

**Parameters:**
- `key` - The storage key
- `value` - The value to store

### `kv_delete`

Remove a stored value.

**Parameters:**
- `key` - The storage key to delete

## Work Items

### `create_comment`

Add a comment to a work item.

**Parameters:**
- `item_id` - The work item ID
- `content` - Comment text (supports markdown)

## SCM (Source Code Management)

### `scm_create_branch`

Create a new branch in a linked repository.

**Parameters:**
- `repository` - Repository identifier
- `branch_name` - Name for the new branch
- `base_branch` - Base branch to create from

### `scm_create_item_link`

Link a work item to an SCM resource (branch, PR, commit).

**Parameters:**
- `item_id` - The work item ID
- `resource_type` - Type of SCM resource (branch, pull_request, commit)
- `resource_url` - URL of the SCM resource

## CLI

### `cli_exec`

Execute a CLI command on the server.

**Parameters:**
- `command` - The command to execute
- `args` - Command arguments (array of strings)

**Returns:** Command output (stdout)

**Note:** Command execution is subject to the plugin's timeout limit (default: 5 seconds).

## Function Summary

| Function | Category | Description |
|----------|----------|-------------|
| `log` | Logging | Write to server log |
| `http_fetch` | HTTP | Make HTTP requests |
| `smtp_send` | Email | Send emails via SMTP |
| `kv_get` | Storage | Read from key-value store |
| `kv_set` | Storage | Write to key-value store |
| `kv_delete` | Storage | Delete from key-value store |
| `create_comment` | Items | Add comment to work item |
| `scm_create_branch` | SCM | Create repository branch |
| `scm_create_item_link` | SCM | Link item to SCM resource |
| `cli_exec` | CLI | Execute system command |