### Install Project Dependencies

Source: https://github.com/elgatosf/streamdeck/blob/main/CONTRIBUTING.md

Installs all necessary dependencies for the project using pnpm.

```bash
pnpm install
```

--------------------------------

### Start Development Environment

Source: https://github.com/elgatosf/streamdeck/blob/main/CONTRIBUTING.md

Launches the development server for active development.

```bash
pnpm dev
```

--------------------------------

### Volume Control Example

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

An example of controlling system volume using dial actions. Requires appropriate system permissions.

```typescript
import { DialAction, DialRotateEvent } from "@elgato/streamdeck";
import { setVolume, getVolume } from "./system-audio"; // Assuming these functions exist

export default class VolumeAction extends DialAction {
  constructor() {
    super();
    this.onDialRotate(({ regex, payload }: DialRotateEvent) => {
      if (regex.test(payload.settings.uuid)) {
        const { ticks } = payload;
        const currentVolume = getVolume(); // Get current volume
        const newVolume = Math.max(0, Math.min(100, currentVolume + ticks * 5)); // Adjust volume by 5% per tick
        setVolume(newVolume);
        this.setTitle(`Vol: ${newVolume}%`);
      }
    });
  }
}
```

--------------------------------

### Counter Action Example

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

A common pattern example demonstrating a counter that increments when a key is pressed.

```typescript
import { KeyAction, KeyDownEvent } from "@elgato/streamdeck";

export default class CounterAction extends KeyAction {
  private count = 0;

  constructor() {
    super();
    this.onKeyDown(({ regex, payload }: KeyDownEvent) => {
      if (regex.test(payload.settings.uuid)) {
        this.count++;
        this.setTitle(`Count: ${this.count}`);
      }
    });
  }
}
```

--------------------------------

### UI Bridge Example

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Shows how to communicate between the plugin and a Property Inspector (UI) using `sendToPlugin` and `sendToPropertyInspector`.

```typescript
import { Action, ActionContext, SendToPluginEvent, PropertyInspectorDidAppearEvent } from "@elgato/streamdeck";

class MyUIAction extends Action {
  constructor() {
    super();

    // Listen for messages from the Property Inspector
    this.onSendToPlugin(({ payload }: SendToPluginEvent) => {
      console.log("Message from PI:", payload);
      if (payload.action === "updateTitle") {
        this.setTitle(payload.value);
      }
    });

    // When the PI appears, send it initial data
    this.onPropertyInspectorDidAppear(({ regex, payload }: PropertyInspectorDidAppearEvent) => {
      if (regex.test(payload.settings.uuid)) {
        this.sendToPropertyInspector({
          event: "initialData",
          data: { currentTitle: "Initial Title" }
        });
      }
    });
  }
}
```

--------------------------------

### Install Stream Deck CLI

Source: https://github.com/elgatosf/streamdeck/blob/main/README.md

Installs the latest version of the Stream Deck CLI globally using npm. This tool is essential for creating, testing, and bundling Stream Deck plugins.

```bash
npm install -g @elgato/cli@latest
```

--------------------------------

### Settings Management Flow (Set and Get)

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Details the data flow for managing action settings, including both setting new values and retrieving existing ones. The 'set' flow involves sending a command and waiting for confirmation, while 'get' involves a request and waiting for a specific event.

```text
action.setSettings({ ... })
    ↓
Send setSettings command
    ↓
Stream Deck receives command
    ↓
Settings updated in Stream Deck
    ↓
Promise resolves

(Separate flow):
action.getSettings()
    ↓
Send getSettings with UUID
    ↓
Wait for didReceiveSettings event
    ↓
Return settings from event
    ↓
Promise resolves (or timeout after 15s)
```

--------------------------------

### Create New Stream Deck Plugin

Source: https://github.com/elgatosf/streamdeck/blob/main/README.md

Initializes the Stream Deck plugin creation wizard. This command guides you through setting up a new plugin project.

```bash
streamdeck create
```

--------------------------------

### Toggle Action Example

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Demonstrates a toggle action that switches between two states (e.g., on/off) when a key is pressed.

```typescript
import { KeyAction, KeyDownEvent } from "@elgato/streamdeck";

export default class ToggleAction extends KeyAction {
  private isOn = false;

  constructor() {
    super();
    this.onKeyDown(({ regex, payload }: KeyDownEvent) => {
      if (regex.test(payload.settings.uuid)) {
        this.isOn = !this.isOn;
        this.setState(this.isOn ? 1 : 0);
        this.setTitle(this.isOn ? "ON" : "OFF");
      }
    });
  }
}
```

--------------------------------

### Manage Plugin Settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Demonstrates how to get, set, and listen for changes to global plugin settings. Use this to persist configuration data for your plugin.

```typescript
// Get global settings
const globalSettings = await streamDeck.settings.getGlobalSettings<MyGlobalSettings>();

// Save global settings
await streamDeck.settings.setGlobalSettings({ apiKey: "..." });

// Listen for changes
streamDeck.settings.onDidReceiveSettings((ev) => {
    console.log("Action settings updated:", ev.payload.settings);
});
```

--------------------------------

### Example Action with Key Down Event

Source: https://github.com/elgatosf/streamdeck/blob/main/README.md

Demonstrates a basic Stream Deck action that listens for a key press (keyDown event) and sets the title of the action to 'Hello world'. Ensure you have the necessary imports from '@elgato/streamdeck'.

```typescript
import { action, KeyDownEvent, SingletonAction } from "@elgato/streamdeck";

@action({ UUID: "com.elgato.hello-world.say-hello" })
export class SayHelloAction extends SingletonAction {
    /**
     * Listen for the key down event that occurs when a user presses
     * a Stream Deck button, and change the title of the action.
     */
    async onKeyDown(ev: KeyDownEvent) {
        await ev.action.setTitle("Hello world");
    }
}
```

--------------------------------

### Example Usage of Target Enum

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/types.md

Demonstrates how to use the Target enum to specify updating only the hardware when setting an icon.

```typescript
await action.setImage("icon.png", { target: Target.Hardware });
```

--------------------------------

### Get Action Settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Retrieve the settings for the current action. Refer to the API reference for more details.

```javascript
action.getSettings()
```

--------------------------------

### Translate Text with i18n Provider

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Example of using the i18n provider to translate a given key. The provider is from `@elgato/utils/i18n`.

```typescript
const translatedKey = streamDeck.i18n.translate("myKey");
```

--------------------------------

### Get Resources for Action

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Retrieves files associated with the action. Requires Stream Deck 7.1 or later.

```typescript
getResources(): Promise<Resources>
```

```typescript
const resources = await action.getResources();
```

--------------------------------

### Settings Management for Actions and Plugins

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Handle settings for both individual action instances and global plugin settings. Includes methods to get, set, and listen for changes in settings.

```typescript
// Action instance settings
const settings = await action.getSettings();
await action.setSettings({ count: 42 });

// Global plugin settings
const global = await streamDeck.settings.getGlobalSettings();
await streamDeck.settings.setGlobalSettings({ apiKey: "secret" });

// Listen for changes
streamDeck.settings.onDidReceiveSettings((ev) => {
    console.log("Settings:", ev.payload.settings);
});
```

--------------------------------

### Settings Namespace Object

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Provides access to global and action-specific settings. Use these functions to get, set, and listen for changes to plugin settings.

```typescript
export const settings = {
    get useExperimentalMessageIdentifiers(): boolean;
    set useExperimentalMessageIdentifiers(value: boolean): void;
    getGlobalSettings<T>(): Promise<T>;
    setGlobalSettings<T>(settings: T): Promise<void>;
    onDidReceiveGlobalSettings<T>(listener: (ev: DidReceiveGlobalSettingsEvent<T>) => void): IDisposable;
    onDidReceiveSettings<T>(listener: (ev: DidReceiveSettingsEvent<T>) => void): IDisposable;
}
```

--------------------------------

### Action: Get Settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Retrieves the currently persisted settings for the action instance.

```typescript
const settings = await action.getSettings();
console.log("Count:", settings.count);
```

--------------------------------

### SDK Version in package.json

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/compatibility.md

Illustrates how to check the installed Stream Deck SDK version by examining the dependencies in your project's package.json file.

```json
{
    "dependencies": {
        "@elgato/streamdeck": "^2.1.0"
    }
}
```

--------------------------------

### Stream Deck Manifest Example for Multi-State Action

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/errors.md

Defines a multi-state action in the manifest.json file, specifying two states with unique names and images. Ensure your action UUID and state definitions match this structure.

```json
{
    "Actions": [
        {
            "UUID": "com.example.multi-state",
            "States": [
                { "Name": "State 0", "Image": "imgs/state0.png" },
                { "Name": "State 1", "Image": "imgs/state1.png" }
            ]
        }
    ]
}
```

--------------------------------

### Manage Resource Files

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Set and get resource files like text or images for your action using `setResources` and `getResources`. This is available from Stream Deck version 7.1 onwards.

```typescript
// Set files
await action.setResources({
    textFile: "c:\\path\\to\\file.txt",
    imageFile: "c:\\path\\to\\image.png"
});

// Get files
const resources = await action.getResources();
console.log(resources.textFile);  // "c:\\path\\to\\file.txt"
```

--------------------------------

### Get and Monitor Stream Deck Devices

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Retrieves a list of all connected Stream Deck devices and sets up a listener for new device connections. Use this to identify and react to device events.

```typescript
const devices = streamDeck.devices.getDevices();
for (const device of devices) {
    console.log(`Device: ${device.name} (${device.type})`);
}

streamDeck.devices.onDeviceDidConnect((ev) => {
    console.log("Device connected:", ev.device.name);
});
```

--------------------------------

### Resources Data Type

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/types.md

A map of resource names to their corresponding file paths associated with an action. An example shows how to retrieve and interpret this map.

```typescript
export type Resources = {
    [key: string]: string;
}
```

```typescript
const resources = await action.getResources();
// { fileOne: "c:\\hello.txt", icon: "c:\\icon.png" }
```

--------------------------------

### Build the Project

Source: https://github.com/elgatosf/streamdeck/blob/main/CONTRIBUTING.md

Compiles and builds the project artifacts.

```bash
pnpm build
```

--------------------------------

### Open URL and Listen for App Launches

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Demonstrates opening a URL in the default browser and listening for application launch events. Requires the streamDeck.system namespace.

```typescript
streamDeck.system.openUrl("https://example.com");

streamDeck.system.onApplicationDidLaunch((ev) => {
    console.log("App launched:", ev.payload.application);
});

const secrets = await streamDeck.system.getSecrets();
```

--------------------------------

### Configure Applications to Monitor

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Specify applications to monitor for launch and termination events. This enables the SDK to trigger system.onApplicationDidLaunch() and system.onApplicationDidTerminate().

```json
{
    "ApplicationsToMonitor": {
        "windows": ["Notepad.exe", "calc.exe"],
        "mac": ["com.apple.TextEdit", "com.apple.Calculator"]
    }
}
```

--------------------------------

### Run All Tests

Source: https://github.com/elgatosf/streamdeck/blob/main/CONTRIBUTING.md

Executes the complete test suite for the project.

```bash
pnpm test
```

--------------------------------

### Initialize and Connect Stream Deck Plugin

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Register actions and connect to the Stream Deck using the SDK. This is the main entry point for your plugin.

```typescript
// plugin.ts or index.ts
import streamDeck from "@elgato/streamdeck";

// Register actions
streamDeck.actions.registerAction(new MyAction());

// Connect to Stream Deck
await streamDeck.connect();
```

--------------------------------

### Access Logger

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Get access to the Stream Deck logger for debugging. Refer to the API reference for more details.

```javascript
streamDeck.logger
```

--------------------------------

### Specify Plugin Entry Point in package.json

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Define the main, exports, and types fields in package.json to specify the plugin's entry point file.

```json
{
    "main": "./dist/plugin/index.js",
    "exports": "./dist/plugin/index.js",
    "types": "./dist/plugin/index.d.ts"
}
```

--------------------------------

### Get Secrets

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Retrieve secrets associated with the Stream Deck system. Refer to the API reference for more details.

```javascript
streamDeck.system.getSecrets()
```

--------------------------------

### Basic Plugin Structure with SingletonAction

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Demonstrates the fundamental structure of a Stream Deck plugin using a SingletonAction. This includes registering an action, handling key down and appearance events, and connecting to the Stream Deck.

```typescript
import streamDeck, { action, SingletonAction, KeyDownEvent } from "@elgato/streamdeck";

@action({ UUID: "com.example.my-plugin.action-one" })
export class MyAction extends SingletonAction {
    async onKeyDown(ev: KeyDownEvent) {
        await ev.action.setTitle("Clicked!");
        await ev.action.showOk();
    }

    async onWillAppear(ev) {
        console.log("Action appeared on device:", ev.device.name);
    }
}

// Initialize
streamDeck.actions.registerAction(new MyAction());
await streamDeck.connect();
```

--------------------------------

### Access Internationalization (i18n) Module

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Get access to the i18n module for localization. Refer to the API reference for more details.

```javascript
streamDeck.i18n
```

--------------------------------

### getSettings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Retrieves settings for the action instance. Use this to load previously saved configuration data for an action.

```APIDOC
## getSettings

### Description
Retrieves settings for the action instance.

### Method
```typescript
getSettings<U extends JsonObject = T>(): Promise<U>
```

### Returns
`Promise<U>` — Settings object.

### Example
```typescript
const settings = await action.getSettings();
console.log("Count:", settings.count);
```
```

--------------------------------

### Access Connection Info

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Get information about the current connection to the Stream Deck. Refer to the API reference for more details.

```javascript
streamDeck.info
```

--------------------------------

### Get Global Settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Retrieve the global settings for the Stream Deck application. Refer to the configuration documentation for more details.

```javascript
streamDeck.settings.getGlobalSettings()
```

--------------------------------

### Create a Singleton Stream Deck Action

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Illustrates how to create a custom Stream Deck action by extending the SingletonAction class and implementing the onKeyDown event.

```typescript
import { action, SingletonAction, KeyDownEvent } from "@elgato/streamdeck";

@action({ UUID: "com.example.my-action" })
export class MyAction extends SingletonAction {
    async onKeyDown(ev: KeyDownEvent) {
        await ev.action.setTitle("Pressed!");
    }
}
```

--------------------------------

### Get Application Language

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/compatibility.md

Retrieves the current language setting of the Stream Deck application. This can be used to localize plugin content.

```typescript
const language = streamDeck.info.application.language;
// Type: "de" | "en" | "es" | "fr" | "ja" | "ko" | "zh_CN" | "zh_TW"
```

--------------------------------

### Access Current Action

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Get information about the current action context within the UI controller. Refer to the API reference for more details.

```javascript
streamDeck.ui.action
```

--------------------------------

### KeyAction.showOk()

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Displays a temporary OK indicator (green check in circle) on the key.

```APIDOC
## KeyAction.showOk()

### Description
Displays a temporary OK indicator (green check in circle) on the key.

### Example
```typescript
await keyAction.showOk();
```
```

--------------------------------

### Get Device by ID

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Retrieve a specific Stream Deck device using its unique identifier. Refer to the API reference for more details.

```javascript
streamDeck.devices.getDeviceById()
```

--------------------------------

### Stream Deck Connection Establishment Flow

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Illustrates the sequence of calls for establishing a WebSocket connection to the Stream Deck. This flow begins with `streamDeck.connect()` and progresses through internal connection and registration steps.

```text
streamDeck.connect()
    ↓
connection.connect() — establish WebSocket
    ↓
Registration parameters received
    ↓
Device instances created
    ↓
Ready to handle events
```

--------------------------------

### Get User's Application Language

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Retrieve the language setting of the user's Stream Deck application. This is useful for internationalization.

```typescript
const language = streamDeck.info.application.language;
console.log(`User language: ${language}`);
```

--------------------------------

### onDidReceiveSettings()

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Inherited from the settings namespace, this method listens for events related to receiving settings updates for an action.

```APIDOC
## onDidReceiveSettings()

### Description
Inherited from settings namespace. Listens for events related to receiving settings updates.

### Method
```typescript
onDidReceiveSettings<T extends JsonObject>(listener: (ev: DidReceiveSettingsEvent<T>) => void): IDisposable
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **listener** ((ev: DidReceiveSettingsEvent<T>) => void) - Required - Callback function to execute when settings are received.

### Request Example
None

### Response
#### Success Response (200)
Returns an `IDisposable` object. Call `.dispose()` on this object to remove the listener.

#### Response Example
None
```

--------------------------------

### Version Checking Pattern

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to check the SDK version. This is useful for ensuring compatibility with specific SDK features.

```typescript
import { streamDeck } from "@elgato/streamdeck";

// Check if the SDK version is at least 2.1.0
if (streamDeck.version() >= "2.1.0") {
  console.log("SDK version is compatible.");
} else {
  console.error("SDK version is too old. Please update.");
}
```

--------------------------------

### Stream Deck Singleton

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

The main entry point for all public SDK functionality. It provides access to various services for managing actions, devices, internationalization, and more. The `connect()` method initiates the connection to the Stream Deck software.

```APIDOC
## `streamDeck` Singleton

### Description
The `streamDeck` singleton is the primary interface for interacting with the Stream Deck SDK. It exposes services for managing actions, devices, internationalization, plugin information, logging, profiles, settings, system interactions, and the user interface. Use `connect()` to establish a connection with the Stream Deck software.

### Usage
```typescript
import { streamDeck } from "@elgatosf/streamdeck";

async function initializePlugin() {
    await streamDeck.connect();
    // Access other services like streamDeck.actions, streamDeck.devices, etc.
}
```

### Properties
- **actions**: `ActionService` - Provides access to action-related functionalities.
- **devices**: `DeviceService` - Provides access to device-related functionalities.
- **i18n**: `I18nProvider<Language>` - Provides internationalization support.
- **info**: `RegistrationInfo` - Contains complete registration information about the plugin and its environment.
- **logger**: `Logger` - Provides logging capabilities.
- **profiles**: `ProfilesNamespace` - Provides access to profile management.
- **settings**: `SettingsNamespace` - Provides access to plugin settings.
- **system**: `SystemNamespace` - Provides access to system-level functionalities.
- **ui**: `UIController` - Provides control over the user interface.

### Methods
- **connect()**: `Promise<void>` - Establishes a connection to the Stream Deck software.
```

--------------------------------

### Listen for Settings Changes

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/errors.md

Demonstrates how to subscribe to the onDidReceiveSettings event to detect changes in action settings, both globally and per-action.

```typescript
// Listen for changes
streamDeck.settings.onDidReceiveSettings((ev) => {
    console.log("Settings changed:", ev.payload.settings);
});

// Or per-action
streamDeck.actions.registerAction(
    @action({ UUID: "..." })
    class MyAction extends SingletonAction {
        onDidReceiveSettings(ev) {
            console.log("My action settings:", ev.payload.settings);
        }
    }
);
```

--------------------------------

### Get Actions on a Specific Device

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Retrieve a list of actions associated with a specific Stream Deck device by its ID. This allows for device-specific logic.

```typescript
const device = streamDeck.devices.getDeviceById(deviceId);
for (const action of device.actions) {
    console.log(action.id);
}
```

--------------------------------

### Define Distributable Profiles in Manifest

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Configure distributable profile settings that can be switched using streamDeck.profiles.switchToProfile().

```json
{
    "Profiles": [
        {
            "Name": "Profile One",
            "DeviceType": 0,
            "DontAutoSwitchWhenInstalled": true
        }
    ]
}
```

--------------------------------

### Connection & Initialization

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Manage the connection to the Stream Deck software and access initialization information.

```APIDOC
## Connection & Initialization

### Connect to Stream Deck
- `streamDeck.connect()`: Establishes a connection to the Stream Deck software.

### Stream Deck Info
- `streamDeck.info`: Provides information about the Stream Deck instance.

### Logger
- `streamDeck.logger`: Access to the Stream Deck logger for debugging.

### Internationalization (i18n)
- `streamDeck.i18n`: Provides internationalization utilities.
```

--------------------------------

### Switch Profile on a Specific Device

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Change the active profile on a particular Stream Deck device using its ID. This is useful for multi-device setups.

```typescript
await streamDeck.profiles.switchToProfile(deviceId, "Profile Name");
```

--------------------------------

### onKeyUp()

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Listens for key release events. This allows your plugin to react when a user releases a Stream Deck key.

```APIDOC
## onKeyUp()

### Description
Listens for key release events.

### Method
```typescript
onKeyUp<T extends JsonObject>(listener: (ev: KeyUpEvent<T>) => void): IDisposable
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **listener** ((ev: KeyUpEvent<T>) => void) - Required - Callback function to execute when a key is released.

### Request Example
None

### Response
#### Success Response (200)
Returns an `IDisposable` object. Call `.dispose()` on this object to remove the listener.

#### Response Example
None
```

--------------------------------

### State Data Type

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/types.md

Represents the state of an action, which can be 0 or 1. This applies only to multi-state actions defined in the manifest. An example demonstrates setting the state to 1.

```typescript
export type State = number
```

```typescript
await action.setState(1);
```

--------------------------------

### Type-Safe Settings Usage

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Illustrates how to use settings in a type-safe manner, ensuring data integrity and reducing runtime errors.

```typescript
import { Action, ActionContext } from "@elgato/streamdeck";

interface MySettings {
  count: number;
}

class MyAction extends Action<MySettings> {
  constructor() {
    super();
    this.onDidReceiveSettings(({ settings }: ActionContext<MySettings>) => {
      console.log(`Current count: ${settings.count}`);
    });
  }
}
```

--------------------------------

### Event Listener Usage: Device Connection

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to listen for device connection and disconnection events to manage device availability.

```typescript
import { streamDeck } from "@elgato/streamdeck";

streamDeck.on("deviceDidConnect", (device) => {
  console.log(`Stream Deck device connected: ${device.id}`);
  // You can now interact with this device
});

streamDeck.on("deviceDidDisconnect", (device) => {
  console.log(`Stream Deck device disconnected: ${device.id}`);
  // Handle device disconnection, e.g., update UI
});

// Ensure you connect to the Stream Deck to receive events
streamDeck.connect();
```

--------------------------------

### streamDeck.connect()

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Establishes a connection to the Stream Deck application, allowing the plugin to communicate with the Stream Deck.

```APIDOC
## streamDeck.connect()

### Description
Establishes a connection to the Stream Deck application.

### Method
```typescript
connect(): Promise<void>
```

### Returns
- `Promise<void>` — Resolves when the connection is established and the plugin is ready to communicate with Stream Deck.

### Example
```typescript
import streamDeck from "@elgato/streamdeck";

await streamDeck.connect();
console.log("Connected to Stream Deck");
```
```

--------------------------------

### Set and Get Action Resources

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Associate files with actions (Stream Deck 7.1+) to embed them when exporting. Use this to manage action-specific assets like icons or data files.

```typescript
// Set resources for an action
await action.setResources({
    fileOne: "c:\\Users\\User\\file.txt",
    icon: "c:\\Users\\User\\icon.png"
});

// Get resources
const resources = await action.getResources();
console.log(resources.fileOne);
```

--------------------------------

### Handle Request Timeout for Settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/errors.md

Demonstrates how to catch a 'The request timed out' error when calling getSettings() or getResources(). This is useful for gracefully handling unresponsive Stream Deck applications.

```typescript
try {
    const settings = await action.getSettings();
} catch (error) {
    if (error === "The request timed out") {
        console.error("Stream Deck did not respond");
        // Retry or handle gracefully
    }
}
```

--------------------------------

### Configure Specific Debug Port

Source: https://github.com/elgatosf/streamdeck/blob/main/README.md

Set a specific port for the debug listener by providing CLI arguments as a string in the manifest's Node.js configuration. This is useful for consistent debugging setups.

```json
{
    // ...
    "Nodejs": {
        "Version": "24",
        "Debug": "--inspect=127.0.0.1:12345"
    },
}
```

--------------------------------

### Switch to Profile

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Programmatically switch to a specified profile. Refer to the API reference for more details.

```javascript
streamDeck.profiles.switchToProfile()
```

--------------------------------

### System Integration

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Perform system-level operations such as opening URLs and monitoring application events.

```APIDOC
## System Integration

### Open URL
- `streamDeck.system.openUrl(url)`: Opens the specified URL in the default browser.

### Application Monitoring
- `onApplicationDidLaunch(application)`: Event triggered when an application launches.
- `onApplicationDidTerminate(application)`: Event triggered when an application terminates.

### Deep Links
- `onDidReceiveDeepLink(deepLink)`: Event triggered when a deep link is received.

### System Wake Event
- `onSystemDidWakeUp()`: Event triggered when the system wakes up.
```

--------------------------------

### Feedback Payload Data Type

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/types.md

An object used to update encoder/dial layout items. It supports various value types including Bar, GBar, Pixmap, Text, number, and string. An example demonstrates setting title, level, and icon.

```typescript
export type FeedbackPayload = Record<string, Bar | GBar | Pixmap | Text | number | string>
```

```typescript
await dialAction.setFeedback({
    title: "Volume",
    level: 75,
    icon: "base64:iVBORw0K..."
});
```

--------------------------------

### Settings Management

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Handles global and instance-specific settings for the Stream Deck plugin.

```APIDOC
## Settings Management

### Description
Provides functions to get and set global and instance-specific settings, and to listen for settings changes.

### Methods
- **`settings.getGlobalSettings<T>(): Promise<T>`**: Retrieves the global settings for the plugin.
- **`settings.setGlobalSettings<T>(settings: T): Promise<void>`**: Sets the global settings for the plugin.
- **`settings.onDidReceiveGlobalSettings<T>(listener: (ev: DidReceiveGlobalSettingsEvent<T>) => void): IDisposable`**: Registers a listener for when global settings are received.
- **`settings.onDidReceiveSettings<T>(listener: (ev: DidReceiveSettingsEvent<T>) => void): IDisposable`**: Registers a listener for when instance-specific settings are received.
```

--------------------------------

### System Integration Features

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Interact with the operating system, such as opening URLs, monitoring application launches, handling deep links, responding to system wake-up events, and accessing secrets.

```typescript
// Open URL
await streamDeck.system.openUrl("https://example.com");

// Monitor applications
streamDeck.system.onApplicationDidLaunch((ev) => {
    console.log("App launched:", ev.payload.application);
});

// Deep links
streamDeck.system.onDidReceiveDeepLink((ev) => {
    console.log("Deep link:", ev.payload.url);
});

// Wake up event
streamDeck.system.onSystemDidWakeUp((ev) => {
    console.log("System woke up");
});

// Secrets (Stream Deck 6.9+)
const secrets = await streamDeck.system.getSecrets();
```

--------------------------------

### Action Registration and Event Routing Flow

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Describes the process of registering an action and how events are routed to the correct action instance. This flow covers action registration, event reception, and dispatching to the action's event handlers.

```text
streamDeck.actions.registerAction(MyAction)
    ↓
manifestId linked to MyAction instance
    ↓
Event received (e.g., keyDown)
    ↓
ActionService routes to matching action
    ↓
MyAction.onKeyDown() called
```

--------------------------------

### Implement a Counter Action

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Create a counter action that increments a count stored in settings on each key press. It updates the action's title and shows an OK confirmation.

```typescript
type CounterSettings = { count: number };

@action({ UUID: "com.example.counter" })
class CounterAction extends SingletonAction<CounterSettings> {
    async onKeyDown(ev: KeyDownEvent<CounterSettings>) {
        const settings = await ev.action.getSettings<CounterSettings>();
        const newCount = (settings.count ?? 0) + 1;
        await ev.action.setSettings({ count: newCount });
        await ev.action.setTitle(String(newCount));
        await ev.action.showOk();
    }
}
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/elgatosf/streamdeck/blob/main/CONTRIBUTING.md

Executes tests and generates a code coverage report.

```bash
pnpm test:coverage
```

--------------------------------

### Registering Global Event Listeners

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Set up global listeners for various event types, including action, device, settings, UI, and system events.

```typescript
// Action events
streamDeck.actions.onKeyDown((ev) => { });
streamDeck.actions.onKeyUp((ev) => { });
streamDeck.actions.onDialDown((ev) => { });
streamDeck.actions.onWillAppear((ev) => { });
streamDeck.actions.onWillDisappear((ev) => { });

// Device events
streamDeck.devices.onDeviceDidConnect((ev) => { });
streamDeck.devices.onDeviceDidDisconnect((ev) => { });
streamDeck.devices.onDeviceDidChange((ev) => { });

// Settings events
streamDeck.settings.onDidReceiveSettings((ev) => { });
streamDeck.settings.onDidReceiveGlobalSettings((ev) => { });

// UI events
streamDeck.ui.onSendToPlugin((ev) => { });
streamDeck.ui.onDidAppear((ev) => { });
streamDeck.ui.onDidDisappear((ev) => { });

// System events
streamDeck.system.onApplicationDidLaunch((ev) => { });
streamDeck.system.onApplicationDidTerminate((ev) => { });
streamDeck.system.onDidReceiveDeepLink((ev) => { });
streamDeck.system.onSystemDidWakeUp((ev) => { });
```

--------------------------------

### Stream Deck Singleton Instance

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

The main export providing access to all public SDK functionality. Use this singleton to interact with devices, actions, settings, and more. Call `connect()` to establish a connection.

```typescript
export const streamDeck = {
    get actions(): ActionService;
    get devices(): DeviceService;
    get i18n(): I18nProvider<Language>;
    get info(): RegistrationInfo;
    get logger(): Logger;
    get profiles(): ProfilesNamespace;
    get settings(): SettingsNamespace;
    get system(): SystemNamespace;
    get ui(): UIController;
    connect(): Promise<void>;
}
```

--------------------------------

### Use Stream Deck Logger

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Demonstrates logging informational and error messages using the Stream Deck logger instance. The logger is provided by `@elgato/utils/logging`.

```typescript
streamDeck.logger.info("Plugin started");
streamDeck.logger.error("An error occurred");
```

--------------------------------

### Open URL

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Open a specified URL in the default web browser. Refer to the API reference for more details.

```javascript
streamDeck.system.openUrl()
```

--------------------------------

### Interact with Property Inspector

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Shows how to send data to the property inspector and listen for messages from it. Also demonstrates checking the current action.

```typescript
// Send data to property inspector
await streamDeck.ui.sendToPropertyInspector({ status: "ready" });

// Listen for messages from property inspector
streamDeck.ui.onSendToPlugin((ev) => {
    console.log("Message from UI:", ev.payload);
});

// Check current action
if (streamDeck.ui.action) {
    console.log("UI for action:", streamDeck.ui.action.id);
}
```

--------------------------------

### Action: Set Resources

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Sets files associated with the action. Requires Stream Deck 7.1+. The input is a map of key to file path.

```typescript
await action.setResources({
    fileOne: "c:\\hello.txt",
    icon: "c:\\icon.png"
});
```

--------------------------------

### System Event Listeners and Open URL

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Provides functions to listen for system-level events like application launches and wake-ups, and to open external URLs. Use these for application lifecycle monitoring and external interactions.

```typescript
export function onApplicationDidLaunch(listener: (ev: ApplicationDidLaunchEvent) => void): IDisposable;
export function onApplicationDidTerminate(listener: (ev: ApplicationDidTerminateEvent) => void): IDisposable;
export function onDidReceiveDeepLink(listener: (ev: DidReceiveDeepLinkEvent) => void): IDisposable;
export function onSystemDidWakeUp(listener: (ev: SystemDidWakeUpEvent) => void): IDisposable;
export function openUrl(url: string): Promise<void>;
export function getSecrets<T>(): Promise<T>;
```

--------------------------------

### Set Image Using Relative Path

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Set an action's image using a path relative to the plugin folder. This approach ensures cross-platform compatibility.

```typescript
// Good: Works on both Windows and macOS
await action.setImage("imgs/icon.png");
```

--------------------------------

### onWillAppear()

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Listens for action appear events. This event is triggered when an action becomes visible on the Stream Deck.

```APIDOC
## onWillAppear()

### Description
Listens for action appear events.

### Method
```typescript
onWillAppear<T extends JsonObject>(listener: (ev: WillAppearEvent<T>) => void): IDisposable
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **listener** ((ev: WillAppearEvent<T>) => void) - Required - Callback function to execute when an action appears.

### Request Example
None

### Response
#### Success Response (200)
Returns an `IDisposable` object. Call `.dispose()` on this object to remove the listener.

#### Response Example
None
```

--------------------------------

### KeyAction Class

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

Extends the base `Action` class to provide key-specific operations. It allows setting images, titles, states, and showing confirmation messages, tailored for key-based actions.

```APIDOC
## `KeyAction<T>` Class

### Description
The `KeyAction` class extends the base `Action` class and is specifically designed for key-based actions on the Stream Deck. It provides methods to manipulate the visual appearance and state of a key, such as setting its image, title, and showing a confirmation state. It also provides information about the key's coordinates and whether it's part of a multi-action.

### Usage
```typescript
import { KeyAction } from "@elgatosf/streamdeck";

class MyKeyAction extends KeyAction {
    // ... implementation ...
}
```

### Properties
- **coordinates**: `Coordinates | undefined` - The coordinates of the key on the Stream Deck.

### Methods
- **isInMultiAction()**: `boolean` - Returns `true` if the key is part of a multi-action, `false` otherwise.
- **setImage(image?: string, options?: ImageOptions)**: `Promise<void>` - Sets the image displayed on the key. Accepts an optional `ImageOptions` object.
- **setState(state: State)**: `Promise<void>` - Sets the visual state of the key.
- **setTitle(title?: string, options?: TitleOptions)**: `Promise<void>` - Sets the title displayed on the key. Accepts an optional `TitleOptions` object.
- **showOk()**: `Promise<void>` - Displays a visual confirmation (e.g., a checkmark) on the key.
```

--------------------------------

### Accessing Stream Deck and Plugin Version Information

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/compatibility.md

Shows how to retrieve the Stream Deck application version, plugin version from the manifest, plugin UUID, and platform details at runtime.

```typescript
// Stream Deck version
const sdVersion = streamDeck.info.application.version;  // "7.1.0"

// Plugin version (from manifest)
const pluginVersion = streamDeck.info.plugin.version;   // "1.0.0"

// Plugin UUID
const pluginId = streamDeck.info.plugin.uuid;           // "com.example.plugin"

// Platform
const platform = streamDeck.info.application.platform;  // "windows" | "mac"
const platformVersion = streamDeck.info.application.platformVersion;  // "10", "11", etc.
```

--------------------------------

### Implement a Dial Volume Control

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Create a dial action to control volume. It uses `setFeedbackLayout` and `setFeedback` to display a volume bar and updates the volume based on dial rotation.

```typescript
@action({ UUID: "com.example.volume" })
class VolumeAction extends SingletonAction {
    private volume = 50;

    async onWillAppear(ev: WillAppearEvent) {
        if (ev.action.isDial()) {
            await ev.action.setFeedbackLayout("bar");
            await ev.action.setFeedback({ level: this.volume });
        }
    }

    async onDialRotate(ev: DialRotateEvent) {
        this.volume = Math.max(0, Math.min(100, this.volume + ev.payload.ticks * 5));
        await ev.action.setFeedback({ level: this.volume });
    }
}
```

--------------------------------

### Profile Management

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Switch between different Stream Deck profiles.

```APIDOC
## Profile Management

### Switch Profile
- `streamDeck.profiles.switchToProfile(profileName, deviceId)`: Switches to the specified profile on a given device.
```

--------------------------------

### Basic Plugin Structure Template

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

A minimal template for a Stream Deck plugin, showing the basic structure and entry point.

```typescript
import { streamDeck, Action } from "@elgato/streamdeck";

// Define your action classes here
class MyAction extends Action {
  constructor() {
    super();
    // Add event listeners and logic for your action
    this.onKeyDown(({ payload }) => {
      console.log("Key pressed:", payload.userالinput);
    });
  }
}

// Register your actions
streamDeck.actions.registerAction(new MyAction());

// Connect to the Stream Deck
streamDeck.connect();

console.log("Plugin loaded and connected.");
```

--------------------------------

### Type-Safe Settings and Event Narrowing

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/compatibility.md

Demonstrates how to use TypeScript for type-safe settings and event payload narrowing within the Stream Deck SDK. Ensures properties exist and methods are available based on action types.

```typescript
// ✓ Type-safe generic settings
type MySettings = { volume: number; enabled: boolean };
const settings = await action.getSettings<MySettings>();
console.log(settings.volume);      // ✓ Known property
console.log(settings.unknown);     // ✗ Type error

// ✓ Event type narrowing
if (action.isDial()) {
    // TypeScript knows this is DialAction<T>
    await action.setFeedbackLayout("...");  // ✓ Method exists
}

// ✓ Event payload types
ev.payload.ticks;  // ✓ Available on DialRotateEvent
ev.payload.hold;   // ✗ Only on TouchTapEvent
```

--------------------------------

### Device Information Retrieval and Event Handling

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/quick-reference.md

Access information about connected Stream Deck devices, including their names, types, grid sizes, and connection status. Also demonstrates listening for device connection events.

```typescript
// Get all devices
for (const device of streamDeck.devices.getDevices()) {
    console.log(`${device.name}: ${device.type}`);
    console.log(`Grid: ${device.size.columns}x${device.size.rows}`);
    console.log(`Connected: ${device.isConnected}`);
}

// Get specific device
const device = streamDeck.devices.getDeviceById(deviceId);

// Listen for device events
streamDeck.devices.onDeviceDidConnect((ev) => {
    console.log("Connected:", ev.device.name);
});
```

--------------------------------

### ApplicationDidLaunchEvent

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/types.md

Event triggered when a monitored application launches. It includes the bundle or package identifier of the launched application.

```APIDOC
## ApplicationDidLaunchEvent

### Description
Event triggered when a monitored application launches.

### Payload Fields
| Field | Type | Description |
|---|---|---|
| application | string | Bundle/package identifier of the launched app |

### Type
```typescript
export type ApplicationDidLaunchEvent = ApplicationEvent<ApplicationDidLaunch>
```
```

--------------------------------

### Register Action and Listen for Key Down Events

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Registers a custom action and sets up a listener for key press events. Use this to define custom behavior for Stream Deck keys.

```typescript
streamDeck.actions.registerAction(new MyCustomAction());

streamDeck.actions.onKeyDown((ev) => {
    console.log("Key pressed:", ev.action.id);
});
```

--------------------------------

### streamDeck.settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Provides methods for persisting and retrieving plugin settings, including global settings and action-specific settings.

```APIDOC
## streamDeck.settings

### Description
Namespace for persisting and retrieving settings.

### Method
```typescript
get settings(): Settings
```

### Key Methods
- `getGlobalSettings<T>()` — Get plugin-level settings
- `setGlobalSettings(settings)` — Save plugin-level settings
- `onDidReceiveSettings()` — Listen for action instance settings changes
- `onDidReceiveGlobalSettings()` — Listen for global settings changes
- `useExperimentalMessageIdentifiers` — Boolean property for message ID behavior

### Example
```typescript
// Get global settings
const globalSettings = await streamDeck.settings.getGlobalSettings<MyGlobalSettings>();

// Save global settings
await streamDeck.settings.setGlobalSettings({ apiKey: "..." });

// Listen for changes
streamDeck.settings.onDidReceiveSettings((ev) => {
    console.log("Action settings updated:", ev.payload.settings);
});
```
```

--------------------------------

### Save and Retrieve Action Instance Settings

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Save and retrieve settings specific to an action placement. Settings persist across Stream Deck restarts and are user-specific.

```typescript
// Save settings for this action
await action.setSettings({ count: 5, enabled: true });

// Retrieve settings
const settings = await action.getSettings();
console.log(settings.count);
```

--------------------------------

### Set Image Using Hardcoded Path (Less Ideal)

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/configuration.md

Set an action's image using a hardcoded, platform-specific path. This is less ideal due to potential compatibility issues.

```typescript
// Less ideal: Hardcoded path
await action.setImage("C:\\Users\\User\\plugin\\icon.png");
```

--------------------------------

### Error Handling Pattern: Version Requirement

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Illustrates how to handle errors related to unmet Stream Deck or SDK version requirements.

```typescript
import { streamDeck, StreamDeckError } from "@elgato/streamdeck";

const REQUIRED_SDK_VERSION = "2.1.0";

if (streamDeck.version() < REQUIRED_SDK_VERSION) {
  throw new StreamDeckError("VERSION_MISMATCH", {
    required: REQUIRED_SDK_VERSION,
    current: streamDeck.version(),
  });
}

try {
  streamDeck.connect();
} catch (error) {
  if (error instanceof StreamDeckError && error.code === "VERSION_MISMATCH") {
    console.error(`Error: SDK version ${error.details.current} is too old. Required: ${error.details.required}.`);
    // Provide instructions to update the SDK
  } else {
    console.error("An unexpected error occurred:", error);
  }
}
```

--------------------------------

### streamDeck.info

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/api-reference.md

Provides access to registration and application information supplied by Stream Deck during initialization.

```APIDOC
## streamDeck.info

### Description
Registration and application information provided by Stream Deck during initialization.

### Method
```typescript
get info(): Omit<RegistrationInfo, "devices">
```

### Returns
- `RegistrationInfo` (without devices) — Contains application details, plugin info, and system information.

### Properties
| Property | Type | Description |
|----------|------|-------------|
| application.font | string | Font used by Stream Deck application |
| application.language | Language | User's preferred language |
| application.platform | "mac" \| "windows" | Operating system |
| application.platformVersion | string | OS version |
| application.version | string | Stream Deck application version |
| colors | object | UI colors (buttonMouseOverBackgroundColor, buttonPressedBackgroundColor, etc.) |
| devicePixelRatio | number | DPI scaling factor |
| plugin.uuid | string | Unique plugin identifier |
| plugin.version | string | Plugin version |

### Example
```typescript
console.log(`Stream Deck ${streamDeck.info.application.version}`);
console.log(`Running on ${streamDeck.info.application.platform}`);
console.log(`Language: ${streamDeck.info.application.language}`);
```
```

--------------------------------

### Error Handling Pattern: Device Not Found

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/MANIFEST.txt

Shows how to catch and handle the 'Device Not Found' error, which can occur if the Stream Deck device is disconnected or not recognized.

```typescript
import { streamDeck, StreamDeckError } from "@elgato/streamdeck";

streamDeck.on("deviceDidConnect", (device) => {
  console.log(`Device connected: ${device.id}`);
});

streamDeck.on("deviceDidDisconnect", (device) => {
  console.log(`Device disconnected: ${device.id}`);
});

try {
  // Attempt to interact with a device
  const device = streamDeck.getDevice("some-device-id");
  if (!device) {
    throw new StreamDeckError("DEVICE_NOT_FOUND");
  }
  // ... interact with device
} catch (error) {
  if (error instanceof StreamDeckError && error.code === "DEVICE_NOT_FOUND") {
    console.error("Error: The specified Stream Deck device was not found.");
    // Suggest checking connections or available devices
  } else {
    console.error("An unexpected error occurred:", error);
  }
}
```

--------------------------------

### Base Action Class

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/modules.md

The base `Action` class provides core context and methods for managing settings and resources. It handles request/response patterns and offers type-safe methods for interacting with action-specific data.

```APIDOC
## `Action<T>` Class

### Description
The base `Action` class serves as the foundation for all custom actions. It extends `ActionContext` and provides essential methods for retrieving and setting action settings and resources. It also includes utility methods for showing alerts and checking the action type (key or dial).

### Usage
```typescript
import { Action } from "@elgatosf/streamdeck";

class MyCustomAction extends Action {
    // ... implementation ...
}
```

### Methods
- **getResources()**: `Promise<Resources>` - Asynchronously retrieves the resources associated with the action.
- **getSettings<U extends JsonObject = T>()**: `Promise<U>` - Asynchronously retrieves the settings for the action, with an optional type parameter for type safety.
- **isDial()**: `this is DialAction<T>` - Type guard to check if the action is a `DialAction`.
- **isKey()**: `this is KeyAction<T>` - Type guard to check if the action is a `KeyAction`.
- **setResources(resources: Resources)**: `Promise<void>` - Sets the resources for the action.
- **setSettings<U extends JsonObject = T>(value: U)**: `Promise<void>` - Sets the settings for the action, with an optional type parameter.
- **showAlert()**: `Promise<void>` - Displays an alert on the Stream Deck key.
```

--------------------------------

### Catch Async SDK Method Errors

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/errors.md

Shows how to use a try-catch block to handle potential rejections from asynchronous SDK methods like setTitle() and setImage().

```typescript
try {
    await action.setTitle("Hello");
    await action.setImage("icon.png");
} catch (error) {
    streamDeck.logger.error(`Failed to update action: ${error}`);
}
```

--------------------------------

### Connect to Stream Deck

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Establish a connection to the Stream Deck application. Refer to the API reference for more details.

```javascript
streamDeck.connect()
```

--------------------------------

### Version & Compatibility

Source: https://github.com/elgatosf/streamdeck/blob/main/_autodocs/README.md

Information on Stream Deck version requirements and feature compatibility.

```APIDOC
## Version & Compatibility

### Requirements
- Reference to `compatibility.md` detailing feature requirements by Stream Deck version.

### Runtime Detection
- Reference to `quick-reference.md` on how to check feature availability at runtime.
```