docs: v1.0.0 release (#52)

* docs: v1.0.0 release * docs: v1.0.0 release * deps: fix security alerts * docs: re-order badges * build: update Node.js of build * docs: update docs of action events * refactor: rename Action.controller --------- Co-authored-by: Richard Herman <[email protected]>
elgatosf · Sep 26, 2024 · 4874b15 · 4874b15
1 parent d07590b
commit 4874b15
Show file tree

Hide file tree

Showing 10 changed files with 295 additions and 178 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -24,7 +24,7 @@ jobs:
   Build:
     strategy:
       matrix:
-        node_version: ["20.5.1", "20.8.1"]
+        node_version: ["20.15.0"]
         os: ["macos-latest", "windows-latest"]
 
     runs-on: ${{ matrix.os }}

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -25,7 +25,7 @@ jobs:
       - name: "🗃️ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: "20.8.1"
+          node-version: "20.15.0"
           registry-url: "https://registry.npmjs.org"
 
       - name: "📐 Install dependencies"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,7 +12,35 @@
 
 # Change Log
 
-## 0.4.0-beta.x
+## 1.0.0
+
+### ✨ New
+
+-   Add action tracking, allowing access to currently visible actions.
+    -   `streamDeck.actions` — all visible actions.
+    -   `SingletonAction.actions` — visible actions that match the action's UUID.
+-   Add `setTitle` to `DialAction`, allowing you to set the title of a layout.
+-   Add `Enumerable` class for creating readonly collections.
+-   Add device information to `Action` provided in event arguments.
+-   Add iterator helpers to `streamDeck.devices` and `streamDeck.actions`.
+
+### 🐞 Fix
+
+-   Fix missing language support for Korean (ko).
+-   Fix TypeScript declaration incorrectly exporting types as classes.
+
+### ♻️ Update
+
+-   Remove `streamDeck.actions.createController` in favor of `streamDeck.actions.getActionById`.
+-   Remove `Action.sendToPropertyInspector` in favour of `streamDeck.ui.current.sendToPropertyInspector`.
+-   Remove `ev.deviceId` in favour of `ev.action.device.id`.
+-   Rename `onDidConnect` to `onConnected` within the UI.
+
+### ⬆️ Upgrading
+
+-   For information on breaking changes, and migrating to the this version, read more about [upgrading to v1.0.0](/UPGRADE.md#v1-0-0).
+
+## 0.4.0-beta
 
 ### ✨ New
 

diff --git a/README.md b/README.md
@@ -2,33 +2,31 @@
 
 [![Stream Deck SDK banner](https://images.ctfassets.net/8j9xr8kwdre8/1ihLKCwNWEfPixs27dq0c0/130be66a5173f332e4caa892a3462893/banner.png)](https://docs.elgato.com/sdk)
 
-# Stream Deck SDK (Beta)
+# Stream Deck SDK
 
-[![Stream Deck npm package](https://img.shields.io/npm/v/%40elgato/streamdeck?logo=npm&logoColor=white)](https://www.npmjs.com/package/@elgato/streamdeck)
-[![Build status](https://img.shields.io/github/actions/workflow/status/elgatosf/streamdeck/build.yml?branch=main&label=Build&logo=GitHub)](https://github.com/elgatosf/streamdeck/actions)
 [![SDK documentation](https://img.shields.io/badge/Documentation-2ea043?labelColor=grey&logo=gitbook&logoColor=white)](https://docs.elgato.com/sdk)
-[![Join the Marketplace Makers Discord](https://img.shields.io/badge/Marketplace%20Makers-5662f6?labelColor=grey&logo=discord&logoColor=white)](https://discord.gg/GehBUcu627)
 [![Elgato homepage](https://img.shields.io/badge/Elgato-3431cf?labelColor=grey&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+RWxnYXRvPC90aXRsZT48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJtMTMuODgxOCA4LjM5NjQuMDI2MS4wMTk2IDkuOTQ5NCA1LjcxNzJjLS40ODg0IDIuNzI5LTEuOTE5NiA1LjIyMjMtNC4wMzg0IDcuMDI1M0ExMS45MjYyIDExLjkyNjIgMCAwIDEgMTIuMDk3IDI0Yy0zLjE5MjUgMC02LjE5MzktMS4yNDc3LTguNDUyNy0zLjUxNDRDMS4zODY4IDE4LjIxODguMTQyNyAxNS4yMDQ0LjE0MjcgMTJjMC0zLjIwNDIgMS4yNDQtNi4yMTg3IDMuNTAxNS04LjQ4NTRDNS45MDE5IDEuMjQ4IDguOTAzMiAwIDEyLjA5NyAwYzIuNDM5NCAwIDQuNzg0Ny43MzMzIDYuNzgzIDIuMTE4NyAxLjk1MjYgMS4zNTQgMy40NDY2IDMuMjM1NyA0LjMyMjcgNS40NDIyLjExMTIuMjgyOS4yMTQ5LjU3MzYuMzA1MS44NjU3bC0yLjEyNTUgMS4yMzU5YTkuNDkyNCA5LjQ5MjQgMCAwIDAtLjI2MTktLjg2OTRjLTEuMzU0LTMuODMwMy00Ljk4MTMtNi40MDQ4LTkuMDIzNy02LjQwNDhDNi44MTcxIDIuMzg4MyAyLjUyMiA2LjcwMDUgMi41MjIgMTJjMCA1LjI5OTUgNC4yOTUgOS42MTE1IDkuNTc0OCA5LjYxMTUgMi4wNTIgMCA0LjAwODQtLjY0NDIgNS42NTk2LTEuODY0NyAxLjYxNzItMS4xOTU1IDIuODAzNi0yLjgzMzcgMy40MzA5LTQuNzM2NGwuMDA2NS0uMDQxOUw5LjU5MDYgOC4zMDQ4djcuMjI1Nmw0LjAwMDQtMi4zMTM4IDIuMDYgMS4xODExLTUuOTk2MiAzLjQ2ODgtMi4xMi0xLjIxMjZWNy4xOTQzbDIuMTE3NC0xLjIyNDUgNC4yMzA5IDIuNDI3OS0uMDAxMy0uMDAxMyIvPjwvc3ZnPg==)](https://elgato.com)
+[![Join the Marketplace Makers Discord](https://img.shields.io/badge/Marketplace%20Makers-5662f6?labelColor=grey&logo=discord&logoColor=white)](https://discord.gg/GehBUcu627)
+[![Stream Deck npm package](https://img.shields.io/npm/v/%40elgato/streamdeck?logo=npm&logoColor=white)](https://www.npmjs.com/package/@elgato/streamdeck)
+[![Build status](https://img.shields.io/github/actions/workflow/status/elgatosf/streamdeck/build.yml?branch=main&label=Build&logo=GitHub)](https://github.com/elgatosf/streamdeck/actions)
 
 </div>
 
-Welcome to the Stream Deck SDK for Node.js. Designed to make creating Stream Deck plugins easy, the Stream Deck SDK provides everything you need to connect, communicate and build with Stream Deck, and lets you focus on the fun stuff.
-
-The Stream Deck SDK for Node.js is currently in public beta, and is available to everyone running Stream Deck 6.4 or newer. If you're interested in building plugins and would like to know more, please join our [Marketplace Makers Discord](https://discord.gg/GehBUcu627).
+Welcome to the Stream Deck SDK — Designed to make creating plugins for Stream Deck easy, the Stream Deck SDK provides everything you need to connect and communicate with Stream Deck app, letting you focus on the fun stuff.
 
 > Creating Stream Deck plugins with Node.js requires Node.js v20. When installing Node.js, we recommended using a version manager such as [nvm](https://github.com/creationix/nvm) (macOS) or [nvm-windows](https://github.com/coreybutler/nvm-windows) (Windows).
 
 ## 🚀 Quick Start
 
-We recommend using the [`@elgato/cli`](https://github.com/elgatosf/cli) tool for building Stream Deck plugins as this provides all scaffolding required to get started with a sample "Counter" plugin.
+The [Stream Deck CLI](https://github.com/elgatosf/cli) provides commands for creating, testing, and bundling your plugins, and is the easiest way to get started building for Stream Deck. You can also [learn more about getting started](https://docs.elgato.com/streamdeck/sdk/introduction/getting-started) in our documentation.
 
-Install the CLI.
+1. With Node.js installed, install the CLI.
 
 ```bash
-npm install -g @elgato/cli
+npm install -g @elgato/cli@latest
 ```
 
-Once installed, run the `create` command to initialize the creation wizard.
+2. Once installed, run the `create` command to initialize the creation wizard.
 
 ```bash
 streamdeck create
@@ -38,7 +36,7 @@ streamdeck create
   <img src="./assets/cli-create.gif">
 </p>
 
-## 🗺️ Plugin Structure
+## 📂 File Structure
 
 After creating a plugin with `streamdeck create` you'll be provided with a local environment for building a plugin.
 
@@ -60,31 +58,16 @@ After creating a plugin with `streamdeck create` you'll be provided with a local
 └── tsconfig.json
 ```
 
-### \*.sdPlugin/
-
-The root of the plugin; this folder contains the build output from the source files as well as assets that support the plugin, such as icons, profiles, etc.
-
--   **manifest.json** - plugin metadata (for more information, see [manifest documentation](https://docs.elgato.com/sdk/plugins/manifest)).
--   **bin/** - build output.
--   **imgs/** - assets used by the plugin, such as icons, profiles, etc.
--   **logs/** - logs generated from [`streamDeck.logger`](#-logging).
--   **ui/** - property inspectors of actions.
-
-### src/
-
--   **plugin.ts** - build entry point.
--   **actions/increment-counter.ts** - example "Counter" action.
-
 The `package.json` provides two scripts for building the plugin.
 
 -   `npm run build` - builds the plugin.
 -   `npm run watch` - continuously watches for changes, and hot-reloads the plugin after build.
 
-## ✨ Actions
+## 🎛️ Actions
 
-Actions are the star of the show and enable users to interact with plugins. At their core, actions are classes that fulfil an interface. This enables the SDK to route events, such as key down, dial rotate, etc., emitted from Stream Deck to the appropriate action, as determined by the action's unique-identifier.
+Actions are the star of the show and enable users to interact with your plugin. Actions are represented as classes that inherit from `SingletonAction`, enabling your plugin to receive events from Stream Deck, for example key down, dial rotate, etc.
 
-The following is an example of an action that listens for the `keyDown` event, and then sets the title of the action to "Hello world" after being pressed.
+The following is an example of an action that listens for the `keyDown` event, and then sets the title of the source action.
 
 ```typescript
 import { action, KeyDownEvent, SingletonAction } from "@elgato/streamdeck";
@@ -101,56 +84,11 @@ export class SayHelloAction extends SingletonAction {
 }
 ```
 
-The action's implementation must be registered in the sources' entry point`.
-
-> **src/plugin.ts**
->
-> ```typescript
-> import streamDeck from "@elgato/streamdeck";
->
-> import { SayHelloAction } from "./actions/say-hello";
->
-> // Register the action, and connect to Stream Deck.
-> streamDeck.actions.registerAction(new SayHelloAction());
-> streamDeck.connect();
-> ```
-
-And the action's metadata must be defined within the plugin's manifest file.
-
-> **\*.sdPlugin/manifest.json**
->
-> ```jsonc
-> {
->     // Learn more: https://docs.elgato.com/sdk/plugins/manifest
->     "Actions": [
->         {
->             "Name": "Say Hello",
->             "UUID": "com.elgato.hello-world.say-hello", // Note, this matches the UUID in the action class.
->             "States": [{ "TitleAlignment": "middle" }]
->         }
->     ]
-> }
-> ```
-
-When observing changes with `npm run watch`, the changes will immediately be available within Stream Deck. Altneratively the changes can be built with `npm run build` followed by `streamdeck restart <uuid>`, where `<uuid>` represents the unique-identifier of your plugin.
-
-## 🎛️ Devices
-
-The `streamDeck.devices` collection contains information about known devices associated with the user. This includes information such as the id, name, and type of device. Additionally, as devices may not be connected at all times the `Device` provides insight into the connection status of a device.
+## 🔎 Debugging
 
-```typescript
-import streamDeck from "@elgato/streamdeck";
+Plugins can be debugged using any Node.js debugger, for example Visual Studio Code, Chrome, etc., and by default will have debugging enabled when created with the Stream Deck CLI `streamdeck create` command.
 
-streamDeck.devices.forEach((device) => {
-    // Device information including id, name, type, etc.
-});
-```
-
-## 🐞 Debugging
-
-Plugins can be debugged from all supporting Node.js debuggers, such as Visual Studio Code, Chrome, etc., and by default will have debugging enabled when created with the CLI tool's `streamdeck create` command.
-
-Debugging can be configured from within the plugin's manifest as part the Node.js configuration object.
+You can configure debugging within the [manifest's Node.js configuration](https://docs.elgato.com/streamdeck/sdk/references/manifest#nodejs).
 
 ```jsonc
 {
@@ -171,25 +109,10 @@ There are four available options when configuring the `Debug` property within th
 
 > When running the plugin in either debug mode `"enabled"` or `"break"`, a random available port will be allocated to the debug listener each time the plugin launches. If you wish to listen on a specific port, the `Debug` value can be set to a string of CLI arguments, for example to listen on port `12345`, the `Debug` value would be `--inspect=127.0.0.1:12345`.
 
-## 📄 Logging
-
-The `streamDeck.logger` provides local file-based logging, allowing you to diagnose, track, and debug your plugin. Logs files operate a file-rotation policy and are re-indexed when the plugin starts or the log file exceeds 50MiB, with the 10 most recent log files being retained.
-
-```typescript
-import streamDeck, { LogLevel } from "@elgato/streamdeck";
-
-const logger = streamDeck.logger.createScope("Custom Scope");
-
-logger.error("Error message");
-logger.warn("Warning message");
-logger.info("Information message");
-logger.debug("Debug message"); // ❌ Default level is INFO
-logger.trace("Trace message"); // ❌ Default level is INFO
-
-logger.setLevel(LogLevel.TRACE);
-
-logger.debug("Debug message"); // ✅
-logger.trace("Trace message"); // ✅
-```
+## 📖 Further Reading
 
-> When the log-level is set to `TRACE` **all** communication between the Stream Deck and the plugin will be logged to the file system, this includes all settings. Please ensure sensitive information is not transmitted whilst `TRACE` is active.
+-   [Making your first changes](https://docs.elgato.com/streamdeck/sdk/introduction/your-first-changes).
+-   Learn about [key](https://docs.elgato.com/streamdeck/sdk/guides/keys) and [dial](https://docs.elgato.com/streamdeck/sdk/guides/dials) actions.
+-   Understand your plugin's metadata within the [manifest JSON file](https://docs.elgato.com/streamdeck/sdk/references/manifest)
+-   Bundle your plugin for [distribution](https://docs.elgato.com/streamdeck/sdk/guides/distribution).
+-   Explore [Stream Deck plugin samples](https://github.com/elgatosf/streamdeck-plugin-samples)
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,10 +1,117 @@
 # Upgrade Guide
 
-**Versions**
+### Versions
 
+-   [v1.0.0](#v1-0-0)
 -   [v0.4.0](#v0-4-0)
 -   [v0.2.0](#v0-2-0)
 
+## <a id="v1-0-0"></a>v1.0.0
+
+-   [Keys and Actions](#keys-and-dials)
+-   [Action Controllers](#action-controllers)
+-   [Device ID in Events](#device-id-in-events)
+-   [sendToPropertyInspector](#sendtopropertyinspector)
+-   [UI Connection Events](#ui-connecting-events)
+
+### Keys and Dials
+
+Actions provided to events have been improved to more accurately reflect methods and information available to them. For this reason, some methods may not be available until type-narrowing within events that apply to both keys and dials.
+
+**Before**
+
+```ts
+onWillAppear(ev: WillAppearEvent): void {
+    ev.action.setFeedback({
+        title: "Hello world"
+    });
+}
+```
+
+**After**
+
+```ts
+onWillAppear(ev: WillAppearEvent): void {
+    if (ev.action.isDial()) { // <- Check the action is a dial.
+        ev.action.setFeedback({
+            title: "Hello world"
+        });
+    }
+}
+```
+
+### Action Controllers
+
+Action controllers previously accessible via `streamDeck.actions.createController` have been superseded by visible actions, accessible via `streamDeck.actions.getActionById`.
+
+**Before**
+
+```ts
+streamDeck.actions.createController(id);
+```
+
+**After**
+
+```ts
+streamDeck.actions.getActionById(id);
+```
+
+### Device ID in Events
+
+The device identifier in event arguments has been superseded by the device itself, accessible on the `action` instance.
+
+**Before**
+
+```ts
+onWillAppear(ev: WillAppearEvent): void {
+    ev.deviceId;
+}
+```
+
+**After**
+
+```ts
+onWillAppear(ev: WillAppearEvent): void {
+    ev.action.device.id;
+}
+```
+
+### sendToPropertyInspector
+
+The `Action.sendToPropertyInspector` has been removed, in favour of sending message directly to the current property inspector, to prevent sending messages to actions without a property inspector active.
+
+**Before**
+
+```ts
+onPropertyInspectorDidAppear(ev: PropertyInspectorDidAppearEvent): void {
+    ev.action.sendToPropertyInspector(...);
+}
+```
+
+**After**
+
+```ts
+onPropertyInspectorDidAppear(ev: PropertyInspectorDidAppearEvent): void {
+    streamDeck.ui.current?.sendToPropertyInspector(...);
+}
+```
+
+### UI Connecting Events
+
+The `onDidConnect` event listener has been renamed within the UI to `onConnected`, and a new `onConnecting` event listener has been added to support the start of the connection being initialized.
+
+**Before**
+
+```ts
+streamDeck.onDidConnect(listener);
+```
+
+**After**
+
+```ts
+streamDeck.onConnected(listener);
+```
+
 ## <a id="v0-4-0"></a>v0.4.0
 
 -   [Localization JSON structure](#localization-json-structure)