Puppet Framework provides a complete set of JavaScript APIs that allow you to access Windows system features in your web applications. All APIs are accessed through the puppet global object.

Namespaces

Puppet API is divided into the following namespaces by functionality:

puppet.window     // Window control
puppet.application // Application control
puppet.fs         // File system
puppet.log        // Logging
puppet.system     // System functions
puppet.tray       // Tray icon
puppet.events     // Event system
puppet.device     // Device system
puppet.storage    // Persistent storage

API Features

Asynchronous Operations

Most API methods are asynchronous and return Promise objects.

// Async call
await puppet.window.setBorderless(true);

// Using Promise
puppet.window.setBorderless(true)
    .then(() => console.log('Window set to borderless'))
    .catch(err => console.error('Operation failed:', err));

Error Handling

All API methods may throw exceptions, it's recommended to use try-catch to catch them.

try {
    await puppet.fs.readFileAsText('config.json');
} catch (error) {
    console.error('Failed to read file:', error.message);
    puppet.log.error('File read failed');
}

Type Support

API methods support multiple data types:

• String: File paths, config values, etc.
• Number: Window position, size, opacity, etc.
• Boolean: Switch options, status flags, etc.
• Object: Config objects, event data, etc.
• Array: File lists, menu items, etc.

Quick Start

Window Control

// Set borderless window
await puppet.window.setBorderless(true);

// Set window opacity
await puppet.window.setOpacity(0.9);

// Center window
await puppet.window.centerWindow();

File Operations

// Open file selection dialog
const files = await puppet.fs.openFileDialog(
    ['Text Files', '*.txt'],
    false
);

// Read file content
const content = await puppet.fs.readFileAsText(files[0]);

// Write file
await puppet.fs.writeTextToFile('output.txt', content);

System Information

// Get system information
const sysInfo = await puppet.system.getSystemInfo();
console.log('OS:', sysInfo.osName);
console.log('CPU:', sysInfo.cpuModel);
console.log('Memory:', sysInfo.totalMemory);

// Take screenshot
const screenshot = await puppet.system.takeScreenShot();

Event Listening

// Monitor USB device insertion
await puppet.events.addEventListener('usb-plug-in', (event) => {
    console.log('USB device inserted:', event.data);
    puppet.log.info('USB device inserted');
});

// Monitor window maximize
await puppet.events.addEventListener('window-maximize', () => {
    console.log('Window maximized');
});

API Naming Conventions

Method Naming

• set: Set properties or states

  • setBorderless()
  • setOpacity()
  • setMenu()

• get: Get properties or information

  • getWindowInfo()
  • getSystemInfo()
  • getDevices()

• is: Query status

  • exists()

• open: Open dialogs

  • openFileDialog()
  • openFolderDialog()

Event Naming

Event names use kebab-case format:

• usb-plug-in: USB device inserted
• usb-plug-out: USB device removed
• window-maximize: Window maximized
• disk-mount: Disk mounted

API Reference

Window Control API

Provides window management functionality, including style control, position adjustment, transparency effects, etc.

• Window Control API Documentation

Application Control API

Provides application lifecycle management and external program execution functionality.

• Application Control API Documentation

File System API

Provides file and folder operations, including read, write, selection, delete, etc.

• File System API Documentation

Logging API

Provides logging functionality for debugging and error tracking.

• Logging API Documentation

System API

Provides system information retrieval, input simulation, screenshot, etc.

• System API Documentation

Tray Icon API

Provides system tray icon management, including menus, notifications, etc.

• Tray Icon API Documentation

Event System API

Provides event listening and handling, supports device and window events.

• Event System API Documentation

Device System API

Provides device query and monitoring functionality.

• Device System API Documentation

Persistent Storage API

Provides SQLite-based key-value storage for data persistence.

• Persistent Storage API Documentation

Version Compatibility

Current API version: v1.2

PUP Format Versions

Puppet Framework supports multiple PUP file formats:

• V1.0: Basic features, supports encryption
• V1.1: Supports startup scripts
• V1.2: Supports digital signatures and certificate verification

V1.2 New Features

V1.2 adds the following security features on top of V1.1:

• Digital Signatures: X.509 certificate-based digital signatures
• Signature Verification: Application and database signature verification
• Certificate Management: Certificate fingerprint, issuer, validity period, etc.
• Database Signatures: Database content signature verification to prevent tampering

Backward Compatibility

Puppet Framework commits to maintaining API backward compatibility while the major version number remains unchanged.

Deprecated APIs

If an API is deprecated, it will be clearly marked in the documentation, and alternatives will be provided.

Limitations and Constraints

Permission Restrictions

• Cannot access Windows system directories
• Cannot execute certain system commands directly (requires user confirmation)

Performance Limitations

• Reading and writing large files may affect performance
• Frequent event monitoring may consume resources

Platform Limitations

• Only supports Windows 10 and above
• Some features require administrator permissions

Security Considerations

Input Validation

Always validate user input:

// Validate file path
if (!path || typeof path !== 'string') {
    throw new Error('Invalid path');
}

Error Handling

Always handle possible errors:

try {
    await riskyOperation();
} catch (error) {
    puppet.log.error('Operation failed:', error.message);
    showError('Operation failed, please try again');
}

Sensitive Data

Don't hardcode sensitive information in code:

// Not recommended
const password = 'my-secret-password';

// Recommended
const password = await loadPasswordFromConfig();

Related Resources

• Microsoft WebView2 Documentation - WebView2 official documentation
• .NET Documentation - .NET framework documentation
• JavaScript Asynchronous Programming - Asynchronous programming guide

Next Steps

We recommend learning the API in this order:

1. Understand Window Control API to create custom windows
2. Learn File System API to perform file operations
3. Explore Event System API to implement event handling
4. Use System API to get system information
5. Reference Tray Icon API to create tray applications

Contributors: bil-fis