@auroraview/sdk


Framework-agnostic SDK for AuroraView WebView bridge. Provides type-safe APIs for communication between JavaScript and Python in AuroraView applications.

Features

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

Installation

``bash
npm install @auroraview/sdk


or

pnpm add @auroraview/sdk

or

yarn add @auroraview/sdk
`

Quick Start

$3

`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' });
`

$3

`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('api.greet');

// Reactive shared state
const [theme, setTheme] = useAuroraState('theme', 'light');

return (



);
}
`

$3

`vue



`

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(method) | Call API with loading/error states |
| useAuroraInvoke(cmd) | Invoke plugin with loading/error states |
| useAuroraState(key, default?) | 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(method) | Call API with reactive loading/error |
| useAuroraInvoke(cmd) | Invoke plugin with reactive loading/error |
| useAuroraState(key, default?) | 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)

License

MIT © AuroraView Contributors

Links

- Documentation
- GitHub Repository
- Issue Tracker