API Reference

import { Plugin, PluginContext, LokusAPI } from '@lokus/plugin-sdk'
 
export default class MyPlugin implements Plugin {
  private api!: LokusAPI
 
  async activate(context: PluginContext) {
    // Access the API
    this.api = context.api
 
    // Use any API
    await this.api.commands.register({
      id: 'myPlugin.hello',
      title: 'Say Hello',
      handler: () => this.api.ui.showNotification('Hello!', 'info')
    })
  }
}

api.commands.register(command: CommandDefinition): Disposable

interface CommandDefinition {
  id: string                    // Unique command ID
  title: string                 // Display title
  handler: CommandHandler       // Command handler function
  category?: string             // Command category
  description?: string          // Description
  icon?: string | ThemeIcon    // Icon
  when?: string                 // When clause
  enablement?: string           // Enablement clause
}
 
type CommandHandler = (...args: any[]) => any | Promise<any>

const disposable = api.commands.register({
  id: 'myPlugin.hello',
  title: 'Say Hello',
  category: 'My Plugin',
  description: 'Shows a greeting message',
  handler: (name?: string) => {
    api.ui.showNotification(`Hello ${name || 'World'}!`, 'info')
  }
})
 
// Unregister command
disposable.dispose()

api.commands.execute<T>(commandId: string, ...args: any[]): Promise<T>

// Execute command without arguments
await api.commands.execute('myPlugin.hello')
 
// Execute command with arguments
await api.commands.execute('myPlugin.hello', 'John')
 
// Execute with typed return value
const result = await api.commands.execute<string>('myPlugin.getData')

api.commands.getAll(): Promise<CommandInfo[]>

const commands = await api.commands.getAll()
commands.forEach(cmd => {
  console.log(`${cmd.id}: ${cmd.title}`)
})

api.commands.exists(commandId: string): Promise<boolean>

if (await api.commands.exists('myPlugin.hello')) {
  console.log('Command is registered')
}

api.editor.getContent(): Promise<string>

const content = await api.editor.getContent()
console.log('Current content:', content)

api.editor.setContent(content: string): Promise<void>

await api.editor.setContent('# Hello World\n\nNew content here')

api.editor.insertContent(content: string): Promise<void>

await api.editor.insertContent('Inserted text')

api.editor.getSelection(): Promise<Selection | undefined>

interface Selection {
  anchor: Position    // Start position
  active: Position    // End position (cursor)
  start: Position     // Min position
  end: Position       // Max position
}
 
interface Position {
  line: number        // Line number (0-based)
  character: number   // Character offset (0-based)
}

const selection = await api.editor.getSelection()
if (selection) {
  console.log(`Selection from ${selection.start.line}:${selection.start.character} to ${selection.end.line}:${selection.end.character}`)
}

api.editor.setSelection(selection: Selection): Promise<void>

await api.editor.setSelection({
  start: { line: 0, character: 0 },
  end: { line: 2, character: 10 }
})

api.editor.getTextInRange(range: Range): Promise<string>

const text = await api.editor.getTextInRange({
  start: { line: 0, character: 0 },
  end: { line: 0, character: 10 }
})

api.editor.replaceText(range: Range, text: string): Promise<void>

await api.editor.replaceText(
  {
    start: { line: 0, character: 0 },
    end: { line: 0, character: 5 }
  },
  'New text'
)

api.editor.registerCompletionProvider(
  selector: DocumentSelector,
  provider: CompletionItemProvider,
  ...triggerCharacters: string[]
): Disposable

api.editor.registerCompletionProvider(
  'markdown',
  {
    provideCompletionItems(document, position, token, context) {
      return [
        {
          label: 'hello',
          kind: CompletionItemKind.Keyword,
          insertText: 'Hello World!',
          documentation: 'Insert greeting'
        }
      ]
    }
  },
  '['  // Trigger on [
)

api.editor.onDidChangeTextDocument(
  listener: (event: TextDocumentChangeEvent) => void
): Disposable

api.editor.onDidChangeTextDocument(event => {
  console.log('Document changed:', event.document.uri)
  event.contentChanges.forEach(change => {
    console.log('Change:', change.text)
  })
})

api.ui.showNotification(
  message: string,
  type?: 'info' | 'warning' | 'error' | 'success',
  actions?: NotificationAction[]
): Promise<string | undefined>

// Simple notification
await api.ui.showNotification('Operation completed', 'success')
 
// With actions
const result = await api.ui.showNotification(
  'File has unsaved changes',
  'warning',
  [
    { id: 'save', label: 'Save', primary: true },
    { id: 'discard', label: 'Discard' }
  ]
)
 
if (result === 'save') {
  // User clicked Save
}

api.ui.showDialog(dialog: DialogOptions): Promise<DialogResult>

const result = await api.ui.showDialog({
  title: 'Confirm Action',
  message: 'Are you sure you want to continue?',
  type: 'question',
  buttons: [
    { id: 'yes', label: 'Yes', primary: true },
    { id: 'no', label: 'No' }
  ],
  checkboxLabel: 'Don\'t ask again',
  checkboxChecked: false
})
 
if (result.buttonId === 'yes') {
  console.log('User confirmed')
  if (result.checkboxChecked) {
    console.log('User checked "Don\'t ask again"')
  }
}

api.ui.showQuickPick<T extends QuickPickItem>(
  items: T[] | Promise<T[]>,
  options?: QuickPickOptions
): Promise<T | undefined>

const items = [
  { label: 'Option 1', description: 'First option' },
  { label: 'Option 2', description: 'Second option' },
  { label: 'Option 3', description: 'Third option' }
]
 
const selected = await api.ui.showQuickPick(items, {
  placeholder: 'Select an option',
  title: 'Quick Pick Example'
})
 
if (selected) {
  console.log('Selected:', selected.label)
}

api.ui.showInputBox(options?: InputBoxOptions): Promise<string | undefined>

const name = await api.ui.showInputBox({
  prompt: 'Enter your name',
  placeholder: 'John Doe',
  validateInput: (value) => {
    if (!value) return 'Name is required'
    if (value.length < 3) return 'Name must be at least 3 characters'
    return null
  }
})
 
if (name) {
  console.log('User entered:', name)
}

api.ui.registerPanel(panel: PanelDefinition): Disposable

api.ui.registerPanel({
  id: 'myPlugin.panel',
  title: 'My Panel',
  type: 'webview',
  location: 'sidebar',
  icon: 'star',
  html: `
    <!DOCTYPE html>
    <html>
      <body>
        <h1>Custom Panel</h1>
        <button onclick="handleClick()">Click Me</button>
        <script>
          function handleClick() {
            window.parent.postMessage({ command: 'buttonClicked' }, '*')
          }
        </script>
      </body>
    </html>
  `
})

api.ui.registerStatusBarItem(
  item: StatusBarItemDefinition
): StatusBarItem

const statusItem = api.ui.registerStatusBarItem({
  id: 'myPlugin.status',
  text: '$(check) Ready',
  tooltip: 'Plugin is ready',
  command: 'myPlugin.showInfo',
  alignment: 'left',
  priority: 100
})
 
// Update later
statusItem.text = '$(sync~spin) Processing...'
 
// Hide
statusItem.hide()
 
// Show
statusItem.show()

api.ui.withProgress<R>(
  options: ProgressOptions,
  task: (progress: Progress, token: CancellationToken) => Promise<R>
): Promise<R>

await api.ui.withProgress(
  {
    location: 'notification',
    title: 'Processing Files',
    cancellable: true
  },
  async (progress, token) => {
    for (let i = 0; i < 100; i++) {
      if (token.isCancellationRequested) {
        break
      }
 
      progress.report({
        message: `Processing file ${i + 1}/100`,
        increment: 1
      })
 
      await processFile(i)
    }
  }
)

readonly workspaceFolders: WorkspaceFolder[] | undefined

const folders = api.workspace.workspaceFolders
if (folders) {
  folders.forEach(folder => {
    console.log(`Folder: ${folder.name} at ${folder.uri}`)
  })
}

api.workspace.findFiles(
  include: string,
  exclude?: string,
  maxResults?: number,
  token?: CancellationToken
): Promise<string[]>

// Find all markdown files
const mdFiles = await api.workspace.findFiles('**/*.md')
 
// Find with exclusions
const tsFiles = await api.workspace.findFiles(
  '**/*.ts',
  '**/node_modules/**',
  100  // Max 100 results
)

api.workspace.onDidChangeWorkspaceFolders(
  listener: (event: WorkspaceFoldersChangeEvent) => void
): Disposable

api.workspace.onDidChangeWorkspaceFolders(event => {
  console.log('Added folders:', event.added)
  console.log('Removed folders:', event.removed)
})

api.fs.readFile(path: string): Promise<string>

const content = await api.fs.readFile('/path/to/file.txt')
console.log(content)

api.fs.writeFile(path: string, content: string): Promise<void>

await api.fs.writeFile('/path/to/file.txt', 'New content')

api.fs.exists(path: string): Promise<boolean>

if (await api.fs.exists('/path/to/file.txt')) {
  console.log('File exists')
}

api.fs.watch(
  path: string,
  listener: (event: FileSystemEvent) => void
): Disposable

const watcher = api.fs.watch('/path/to/directory', event => {
  console.log(`File ${event.type}: ${event.path}`)
})
 
// Stop watching
watcher.dispose()

api.network.fetch(
  url: string,
  options?: RequestInit
): Promise<Response>

// GET request
const response = await api.network.fetch('https://api.example.com/data')
const data = await response.json()
 
// POST request
const response = await api.network.fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'John' })
})

api.storage.get<T>(key: string, defaultValue?: T): Promise<T | undefined>

const settings = await api.storage.get('settings', { enabled: true })

api.storage.set(key: string, value: any): Promise<void>

await api.storage.set('settings', { enabled: true, mode: 'advanced' })

api.storage.delete(key: string): Promise<void>

await api.storage.delete('tempData')

api.storage.keys(): Promise<string[]>

const keys = await api.storage.keys()
console.log('Stored keys:', keys)

api.events.on(
  event: string,
  listener: (data: any) => void
): Disposable

const disposable = api.events.on('myPlugin.dataUpdated', data => {
  console.log('Data updated:', data)
})
 
// Unsubscribe
disposable.dispose()

api.events.emit(event: string, data?: any): void

api.events.emit('myPlugin.dataUpdated', { count: 42 })

api.events.once(
  event: string,
  listener: (data: any) => void
): Disposable

api.events.once('myPlugin.initialized', () => {
  console.log('Plugin initialized')
})

interface Disposable {
  dispose(): void
}

interface Position {
  line: number        // Line number (0-based)
  character: number   // Character offset (0-based)
}

interface Range {
  start: Position
  end: Position
}

interface Selection extends Range {
  anchor: Position    // Selection start
  active: Position    // Cursor position
}

try {
  await api.editor.setContent('New content')
} catch (error) {
  api.ui.showNotification(`Error: ${error.message}`, 'error')
  console.error(error)
}

class APIError extends Error {
  code: APIErrorCode
  details?: Record<string, unknown>
}
 
enum APIErrorCode {
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  INVALID_PARAMS = 'INVALID_PARAMS',
  NOT_FOUND = 'NOT_FOUND',
  NOT_SUPPORTED = 'NOT_SUPPORTED',
  RATE_LIMITED = 'RATE_LIMITED',
  INTERNAL_ERROR = 'INTERNAL_ERROR'
}

try {
  await api.commands.execute('unknown.command')
} catch (error) {
  if (error instanceof APIError) {
    if (error.code === APIErrorCode.NOT_FOUND) {
      console.log('Command not found')
    }
  }
}

export default class MyPlugin implements Plugin {
  private disposables: Disposable[] = []
 
  async activate(context: PluginContext) {
    this.disposables.push(
      api.commands.register({ /* ... */ }),
      api.editor.onDidChangeTextDocument(/* ... */),
      api.fs.watch('/path', /* ... */)
    )
  }
 
  async deactivate() {
    this.disposables.forEach(d => d.dispose())
    this.disposables = []
  }
}

async activate(context: PluginContext) {
  context.subscriptions.push(
    api.commands.register({ /* ... */ }),
    api.editor.onDidChangeTextDocument(/* ... */)
  )
  // Automatically disposed when plugin deactivates
}

// Good
await api.editor.setContent('New content')
await api.storage.set('key', 'value')
 
// Bad - operations may not complete
api.editor.setContent('New content')
api.storage.set('key', 'value')

const input = await api.ui.showInputBox({
  validateInput: (value) => {
    if (!value) return 'Input is required'
    if (value.length < 3) return 'Must be at least 3 characters'
    return null  // Valid
  }
})