Framework-agnostic SDK for AuroraView WebView bridge
npm install @auroraview/sdk

Framework-agnostic SDK for AuroraView WebView bridge. Provides type-safe APIs for communication between JavaScript and Python in AuroraView applications.
- 🎯 Type-safe - Full TypeScript support with comprehensive type definitions
- 🔌 Framework Adapters - First-class support for React and Vue 3
- 📡 IPC Communication - Call Python methods, invoke plugin commands, and emit events
- 🔄 State Sync - Reactive shared state between JavaScript and Python
- 📁 File System API - Read, write, and manage files
- 💬 Dialog API - Native file dialogs and message boxes
- 📋 Clipboard API - Read and write clipboard content
- 🐚 Shell API - Execute commands and open URLs
``bash`
npm install @auroraview/sdkor
pnpm add @auroraview/sdkor
yarn add @auroraview/sdk
`typescript
import { createAuroraView } from '@auroraview/sdk';
const av = createAuroraView();
// Wait for bridge to be ready
await av.whenReady();
// Call a Python method
const result = await av.call('api.greet', { name: 'World' });
// Invoke a plugin command
const files = await av.invoke('plugin:fs|read_dir', { path: '/tmp' });
// Subscribe to events
av.on('custom:event', (data) => {
console.log('Received:', data);
});
// Emit events to Python
av.emit('user:action', { type: 'click' });
`
`tsx
import { useAuroraView, useAuroraEvent, useAuroraCall, useAuroraState } from '@auroraview/sdk/react';
function App() {
const { client, isReady } = useAuroraView();
// Subscribe to events
useAuroraEvent('notification', (data) => {
console.log('Notification:', data);
});
// Call API with loading/error states
const { execute, loading, data, error } = useAuroraCall
// Reactive shared state
const [theme, setTheme] = useAuroraState
return (
Result: {data}
}Error: {error.message}
}$3
`vue
Result: {{ data }}
Error: {{ error.message }}
`API Reference
$3
`typescript
interface AuroraViewClient {
// RPC-style call to Python method
call(method: string, params?: unknown): Promise;
// Invoke plugin command
invoke(cmd: string, args?: Record): Promise;
// Fire-and-forget event to Python
emit(event: string, data?: unknown): void;
// Subscribe to events from Python
on(event: string, handler: (data: T) => void): () => void;
// Subscribe once
once(event: string, handler: (data: T) => void): () => void;
// Unsubscribe
off(event: string, handler?: EventHandler): void;
// Check if bridge is ready
isReady(): boolean;
// Wait for bridge to be ready
whenReady(): Promise;
// Built-in APIs
readonly fs: FileSystemAPI | undefined;
readonly dialog: DialogAPI | undefined;
readonly clipboard: ClipboardAPI | undefined;
readonly shell: ShellAPI | undefined;
readonly state: AuroraViewState | undefined;
}
`$3
| Hook | Description |
|------|-------------|
|
useAuroraView() | Get client instance and ready state |
| useAuroraEvent(event, handler) | Subscribe to an event |
| useAuroraEvents(events) | Subscribe to multiple events |
| useAuroraCall | Call API with loading/error states |
| useAuroraInvoke | Invoke plugin with loading/error states |
| useAuroraState | Reactive shared state |
| useProcessEvents(options) | Subscribe to process stdout/stderr/exit |$3
| Composable | Description |
|------------|-------------|
|
useAuroraView() | Get client ref and ready state |
| useAuroraEvent(event, handler) | Subscribe to an event |
| useAuroraEvents(events) | Subscribe to multiple events |
| useAuroraCall | Call API with reactive loading/error |
| useAuroraInvoke | Invoke plugin with reactive loading/error |
| useAuroraState | Two-way reactive shared state |
| useProcessEvents(options) | Subscribe to process events |$3
`typescript
const av = createAuroraView();// Read file
const content = await av.fs?.readFile('/path/to/file.txt');
// Write file
await av.fs?.writeFile('/path/to/file.txt', 'Hello World');
// Read directory
const entries = await av.fs?.readDir('/path/to/dir', true); // recursive
// Check existence
const exists = await av.fs?.exists('/path/to/file.txt');
// Get file stats
const stat = await av.fs?.stat('/path/to/file.txt');
// Create directory
await av.fs?.createDir('/path/to/new/dir', true); // recursive
// Copy/Move/Delete
await av.fs?.copy('/from', '/to');
await av.fs?.rename('/from', '/to');
await av.fs?.remove('/path', true); // recursive
`$3
`typescript
const av = createAuroraView();// Open file dialog
const { path, cancelled } = await av.dialog?.openFile({
title: 'Select File',
filters: [{ name: 'Images', extensions: ['png', 'jpg'] }]
});
// Open folder dialog
const { path } = await av.dialog?.openFolder();
// Save file dialog
const { path } = await av.dialog?.saveFile({
defaultName: 'document.txt'
});
// Message dialogs
await av.dialog?.info('Operation completed', 'Success');
await av.dialog?.warning('Are you sure?', 'Warning');
await av.dialog?.error('Something went wrong', 'Error');
// Confirmation
const confirmed = await av.dialog?.ask('Delete this file?', 'Confirm');
`$3
`typescript
const av = createAuroraView();// Text
await av.clipboard?.writeText('Hello');
const text = await av.clipboard?.readText();
// Image (base64)
const imageData = await av.clipboard?.readImage();
await av.clipboard?.writeImage(base64Data);
// Clear
await av.clipboard?.clear();
`$3
`typescript
const av = createAuroraView();// Open URL in browser
await av.shell?.open('https://example.com');
// Open file with default app
await av.shell?.openPath('/path/to/document.pdf');
// Show in file manager
await av.shell?.showInFolder('/path/to/file');
// Execute command
const { code, stdout, stderr } = await av.shell?.execute('ls', ['-la']);
// Spawn process (non-blocking)
const { pid } = await av.shell?.spawn('node', ['server.js']);
// Get environment
const path = await av.shell?.getEnv('PATH');
const allEnv = await av.shell?.getEnvAll();
`TypeScript Support
The SDK is written in TypeScript and provides comprehensive type definitions. All APIs are fully typed.
`typescript
import type {
AuroraViewClient,
EventHandler,
FileFilter,
DirEntry,
FileStat,
ExecuteResult,
// ... and more
} from '@auroraview/sdk';
`Browser Compatibility
The SDK is designed to work within AuroraView's WebView environment. It requires:
- ES2020+ support
-
window.auroraview` bridge object (injected by AuroraView runtime)MIT © AuroraView Contributors