> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deskofy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# IPC Commands

The `deskofyApp` API provides a set of application-level IPC commands that allow web applications to interact with native Deskofy features such as application control, history management, and app information.

* **Application-related**: Access and modify application-level details.
* **Navigation-related**: Control and retrieve navigation state within the app.
* **Network-related**: Manage network operations and monitor connectivity.
* **Notification-related**: Send notifications to the user from the Deskofy app.
* **Window-related**: Get or set properties of the application window.

These commands are available **only when the app is running inside the Deskofy environment**.

<Note>
  To safely use these APIs, always verify the runtime environment using `isInDeskofy()` from `@deskofy/core`.
</Note>

# Custom IPCs

`type TDeskofyPlugins = Record<string, any>; ` Represents a key–value map of **custom plugin instances**. Each key corresponds to a plugin name registered in the Deskofy runtime, and each value exposes the plugin’s available methods or data.

You can access all available plugins through the `deskofyPlugins()` function. It returns an object containing all registered plugin APIs.

```typescript theme={null}
import { isInDeskofy, deskofyPlugins } from '@deskofy/core';

const usePlugins = async () => {
  if (!isInDeskofy()) {
    return;
  }

  const plugins = deskofyPlugins();

  if (plugins) {
    console.log('Available plugins:', Object.keys(plugins));
  }
};
```

**Example Usage of a Custom Plugin:**

Assume you have a plugin registered under the name `fileManager` that exposes methods like `openFile()` and `saveFile()`.

```typescript theme={null}
if (isInDeskofy()) {
  const plugins = deskofyPlugins();

  const fileManager = plugins?.fileManager;

  if (fileManager) {
    const file = await fileManager.openFile('/Users/demo/Documents/sample.txt');
    console.log('File content:', file.content);

    await fileManager.saveFile('/Users/demo/Documents/sample.txt', 'Updated content');
    console.log('File saved successfully!');
  }
}
```

# Application-related IPCs

## `getAppUrl(): Promise<string>`

Returns the URL of the current Deskofy application.

```typescript theme={null}
if (isInDeskofy()) {
  const appUrl = await window.deskofyApp.getAppUrl();
  console.log('Deskofy App URL:', appUrl);
}
```

## `quit(): void`

Immediately closes the Deskofy application.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyApp.quit();
}
```

## `restart(): void`

Restarts the Deskofy application.

<Info>
  Useful for applying configuration or environment changes.
</Info>

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyApp.restart();
}
```

## `getHistory(): Promise<{ url: string; title: string; timestamp: number }[]>`

Retrieves the browsing history of the current Deskofy app window.

```typescript theme={null}
if (isInDeskofy()) {
  const history = await window.deskofyApp.getHistory();
  console.table(history);
}
```

## `filterHistory(filters: { url?: string; title?: string }): Promise<{ url: string; title: string; timestamp: number }[]>`

Filters the application history based on a specific URL or title.

```typescript theme={null}
if (isInDeskofy()) {
  const filtered = await window.deskofyApp.filterHistory({ title: 'Dashboard' });
  console.table(filtered);
}
```

## `cleanHistory(): void`

Clears all stored browsing history within the current Deskofy application context.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyApp.cleanHistory();
  console.log('Deskofy app history cleared');
}
```

# Navigation-relates IPCs

## `canGoBack(): Promise<boolean>`

Checks if there is a previous page in the navigation history.

```typescript theme={null}
if (isInDeskofy()) {
  const canGoBack = await window.deskofyNavigation.canGoBack();
  console.log('Can go back?', canGoBack);
}
```

## `canGoForward(): Promise<boolean>`

Checks if there is a next page available in the navigation history.

```typescript theme={null}
if (isInDeskofy()) {
  const canGoForward = await window.deskofyNavigation.canGoForward();
  console.log('Can go forward?', canGoForward);
}
```

## `goBack(): void`

Navigates to the previous page in the current Deskofy window’s history.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNavigation.goBack();
}
```

## `goForward(): void`

Navigates forward to the next page in the Deskofy app’s navigation history.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNavigation.goForward();
}
```

## `cloneWindow(): void`

Creates a duplicate of the current Deskofy application window, effectively cloning the app’s current state into a new window instance.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNavigation.cloneWindow();
  console.log('Cloned current Deskofy window');
}
```

# Network-related IPCs

## `getStatus(): Promise<{ online: boolean }>`

Checks the current network connectivity state of the Deskofy application.

```typescript theme={null}
if (isInDeskofy()) {
  const status = await window.deskofyNetwork.getStatus();
  console.log('Network status:', status.online ? 'Online' : 'Offline');
}
```

## `onStatusChange(callback: (status: { online: boolean }) => void): void`

Listens for changes in the network connectivity status. The provided callback is triggered whenever the connection goes **online** or **offline**.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNetwork.onStatusChange((status) => {
    console.log('Network changed:', status.online ? 'Online' : 'Offline');
  });
}
```

## `speedTest(): Promise<any>`

Performs a network speed test and returns performance metrics.

```typescript theme={null}
if (isInDeskofy()) {
  const result = await window.deskofyNetwork.speedTest();
  console.log('Speed test results:', result);
}
```

# Notification-related IPCs

## `show(options: TNotificationOptions): void`

Displays a native system notification. You can customize the title, body, icon, and add custom action buttons.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNotification.show({
    title: 'Update Available',
    body: 'A new version of your app is ready to install.',
    icon: '/assets/update-icon.png',
    actions: [{ type: 'button', text: 'Restart Now' }],
  });
}
```

## `setBadge(count: number): void`

Sets an application badge (e.g., dock or taskbar icon counter) to indicate unread messages, notifications, or pending tasks.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNotification.setBadge(5); // shows "5" badge
}
```

## `clear(): void`

Clears all active notifications and resets the badge counter.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyNotification.clear();
}
```

## `showAlert(options: TAlertOptions): Promise<void>`

Displays a modal alert dialog with customizable title, message, and buttons.

```typescript theme={null}
if (isInDeskofy()) {
  await window.deskofyNotification.showAlert({
    type: 'info',
    title: 'Welcome',
    message: 'Your project was created successfully!',
    buttons: ['OK'],
  });
}
```

## `showConfirm(options: TConfirmOptions): Promise<number>`

Displays a confirmation dialog with multiple buttons and returns the **index** of the button the user clicked.

```typescript theme={null}
if (isInDeskofy()) {
  const choice = await window.deskofyNotification.showConfirm({
    title: 'Confirm Exit',
    message: 'Are you sure you want to quit the application?',
    buttons: ['Cancel', 'Quit'],
  });

  if (choice === 1) {
    console.log('User confirmed quit');
  }
}
```

# Window-related IPCs

## `minimize(): void`

Minimizes the current Deskofy application window.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.minimize();
}
```

## `maximize(): void`

Maximizes the current Deskofy window to full size.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.maximize();
}
```

## `unmaximize(): void`

Restores the Deskofy window to its previous (non-maximized) size.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.unmaximize();
}
```

## `close(): void`

Closes the current Deskofy window.

<Note>
  If it’s the main window, the application will likely quit.
</Note>

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.close();
}
```

## `toggleFullScreen(): void`

Toggles the current window between fullscreen and windowed mode.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.toggleFullScreen();
}
```

## `focus(): void`

Brings the current Deskofy window to the foreground and focuses it.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.focus();
}
```

## `open(url?: string, config?: any): void`

Opens a new Deskofy window. You can optionally pass a URL and configuration object (for window options, size, etc.).

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.open('https://deskofy.dev/docs', {
    width: 1000,
    height: 700,
    resizable: true,
  });
}
```

## `getBounds(): any`

Retrieves the current window’s size and position. Returns an object similar to `{ x, y, width, height }`.

```typescript theme={null}
if (isInDeskofy()) {
  const bounds = window.deskofyWindow.getBounds();
  console.log('Current window bounds:', bounds);
}
```

## `setBounds(bounds: any): void`

Sets or updates the window’s position and size.

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.setBounds({ width: 1200, height: 800 });
}
```

## `isMaximized(callback: (event: any, state: boolean) => void): any`

Registers a listener to detect changes in the window’s maximized state. The callback receives a `state` boolean (`true` = maximized, `false` = restored).

```typescript theme={null}
if (isInDeskofy()) {
  window.deskofyWindow.isMaximized((_event, state) => {
    console.log('Window maximized?', state);
  });
}
```