feat: embedded resources and message identifiers (#126)

* feat: add message identifiers to settings and global settings

* feat: add embedded resource APIs

* docs: add Stream Deck 7.1 requirement

* refactor: centralize Resources type

* 2.0.0-dev.202510211650

* docs: fix typo

Co-authored-by: Copilot <[email protected]>

* docs: fix typo

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Richard Herman <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: GeekyEggo

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@elgato/streamdeck",
-    "version": "2.0.0-beta",
+    "version": "2.0.0-dev.202510211650",
     "description": "The official Node.js SDK for creating Stream Deck plugins.",
     "main": "./dist/index.js",
     "type": "module",

package.json

@@ -1,6 +1,7 @@
 import type { JsonObject, JsonValue } from "../plugin";
 import type { DidReceiveGlobalSettings, DidReceiveSettings, State } from "./events";
 import type { FeedbackPayload } from "./layout";
+import type { Resources } from "./resources";
 import type { Target } from "./target";
 
 /**
@@ -51,7 +52,12 @@ export type SetSettings = ContextualizedCommandWithPayload<"setSettings", JsonOb
 /**
  * Gets the settings associated with an instance of an action. Causes {@link DidReceiveSettings} to be emitted.
  */
-export type GetSettings = ContextualizedCommand<"getSettings">;
+export type GetSettings = ContextualizedCommand<"getSettings"> & {
+	/**
+	 * Optional identifier that can be used to identify the response to this request.
+	 */
+	id?: string;
+};
 
 /**
  * Sets the global settings associated with the plugin.
@@ -61,13 +67,39 @@ export type SetGlobalSettings = ContextualizedCommandWithPayload<"setGlobalSetti
 /**
  * Gets the global settings associated with the plugin. Causes {@link DidReceiveGlobalSettings} to be emitted.
  */
-export type GetGlobalSettings = ContextualizedCommand<"getGlobalSettings">;
+export type GetGlobalSettings = ContextualizedCommand<"getGlobalSettings"> & {
+	/**
+	 * Optional identifier that can be used to identify the response to this request.
+	 */
+	id?: string;
+};
 
 /**
  * Gets secrets associated with the plugin.
  */
 export type GetSecrets = ContextualizedCommand<"getSecrets">;
 
+/**
+ * Sets the resources (files) associated with the action; these resources are embedded into the action
+ * when it is exported, either individually, or as part of a profile.
+ *
+ * Available from Stream Deck 7.1.
+ */
+export type SetResources = ContextualizedCommandWithPayload<"setResources", Resources>;
+
+/**
+ * Gets the resources (files) associated with the action; these resources are embedded into the action
+ * when it is exported, either individually, or as part of a profile.
+ *
+ * Available from Stream Deck 7.1.
+ */
+export type GetResources = ContextualizedCommand<"getResources"> & {
+	/**
+	 * Optional identifier that can be used to identify the response to this request.
+	 */
+	id?: string;
+};
+
 /**
  * Opens the URL in the user's default browser.
  */
@@ -249,6 +281,7 @@ export type SendToPropertyInspector<TPayload extends JsonValue = JsonValue> = Co
  */
 export type PluginCommand =
 	| GetGlobalSettings
+	| GetResources
 	| GetSecrets
 	| GetSettings
 	| LogMessage
@@ -258,6 +291,7 @@ export type PluginCommand =
 	| SetFeedbackLayout
 	| SetGlobalSettings
 	| SetImage
+	| SetResources
 	| SetSettings
 	| SetState
 	| SetTitle

src/api/command.ts

@@ -1,16 +1,43 @@
 import type { Controller, DeviceType } from "@elgato/schemas/streamdeck/plugins";
 
 import type { JsonObject } from "../../common/json";
+import type { Resources } from "../resources";
 import type { DeviceIdentifier } from "./device";
 import type { EventIdentifier } from "./index";
 
 /**
- * Occurs when the settings associated with an action instance are requested, or when the the settings were updated by the property inspector.
+ * Occurs when the settings associated with an action instance are requested, or when the the settings
+ * were updated in the property inspector.
  */
 export type DidReceiveSettings<TSettings extends JsonObject> = ActionEventMessage<
 	"didReceiveSettings",
 	MultiActionPayload<TSettings> | SingleActionPayload<TSettings>
->;
+> & {
+	/**
+	 * Identifier provided when requesting the settings, used to identify the source of the request.
+	 *
+	 * This is always undefined if the event is received because the settings were changed in the property
+	 * inspector.
+	 */
+	readonly id?: string;
+};
+
+/**
+ * Occurs when the resources associated with an action instance are requested, or when the the resources
+ * were updated in the property inspector.
+ */
+export type DidReceiveResources<TSettings extends JsonObject> = ActionEventMessage<
+	"didReceiveResources",
+	MultiActionPayload<TSettings> | SingleActionPayload<TSettings>
+> & {
+	/**
+	 * Identifier provided when requesting the resources, used to identify the source of the request.
+	 *
+	 * This is always undefined if the event is received because the resources were changed in the property
+	 * inspector.
+	 */
+	readonly id?: string;
+};
 
 /**
  * Occurs when the user updates an action's title settings in the Stream Deck application.
@@ -140,6 +167,13 @@ export type SingleActionPayload<
 	 * NB. Requires Stream Deck 6.7 when accessed from the property inspector.
 	 */
 	readonly isInMultiAction: false;
+
+	/**
+	 * Resources (files) associated with the action.
+	 *
+	 * Available from Stream Deck 7.1.
+	 */
+	readonly resources: Resources;
 };
 
 /**
@@ -160,6 +194,13 @@ export type MultiActionPayload<TSettings extends JsonObject> = ActionPayload<TSe
 	 * NB. Requires Stream Deck 6.7 when accessed from the property inspector.
 	 */
 	readonly isInMultiAction: true;
+
+	/**
+	 * Resources (files) associated with the action.
+	 *
+	 * Available from Stream Deck 7.1.
+	 */
+	readonly resources: Resources;
 };
 
 /**

src/api/events/action.ts

@@ -1,5 +1,11 @@
 import type { JsonObject, JsonValue } from "../../common/json";
-import type { DidReceiveSettings, TitleParametersDidChange, WillAppear, WillDisappear } from "./action";
+import type {
+	DidReceiveResources,
+	DidReceiveSettings,
+	TitleParametersDidChange,
+	WillAppear,
+	WillDisappear,
+} from "./action";
 import type { DeviceDidChange, DeviceDidConnect, DeviceDidDisconnect } from "./device";
 import type { DialDown, DialRotate, DialUp, TouchTap } from "./encoder";
 import type { KeyDown, KeyUp } from "./keypad";
@@ -23,6 +29,7 @@ export { type DeviceIdentifier } from "./device";
 
 export {
 	type Coordinates,
+	type DidReceiveResources,
 	type DidReceiveSettings,
 	type TitleParametersDidChange,
 	type WillAppear,
@@ -69,6 +76,7 @@ export type PluginEvent =
 	| DidReceiveDeepLink
 	| DidReceiveGlobalSettings<JsonObject>
 	| DidReceivePropertyInspectorMessage<JsonValue>
+	| DidReceiveResources<JsonObject>
 	| DidReceiveSecrets<JsonObject>
 	| DidReceiveSettings<JsonObject>
 	| KeyDown<JsonObject>

src/api/events/index.ts

@@ -18,6 +18,13 @@ export type ApplicationDidTerminate = ApplicationEventIdentifier<"applicationDid
  * Occurs when the plugin receives the global settings from Stream Deck.
  */
 export type DidReceiveGlobalSettings<TSettings extends JsonObject> = EventIdentifier<"didReceiveGlobalSettings"> & {
+	/**
+	 * Identifier provided when requesting the settings, used to identify the source of the request.
+	 *
+	 * This is always undefined if the event is received because the settings were changed in the property inspector.
+	 */
+	readonly id?: string;
+
 	/**
 	 * Additional information about the event that occurred.
 	 */

src/api/events/system.ts

@@ -4,6 +4,7 @@ export * from "./events";
 export * from "./i18n";
 export * from "./layout";
 export * from "./registration";
+export * from "./resources";
 export * from "./target";
 
 export { type Manifest } from "@elgato/schemas/streamdeck/plugins";

src/api/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Resources (files) associated with an action, represented as a map of keys and paths, for example.
+ * ```
+ * {
+ *   fileOne: "c:\\hello-world.txt",
+ *   anotherFile: "c:\\icon.png"
+ * }
+ * ```
+ */
+export type Resources = {
+	[key: string]: string;
+};

src/api/resources.ts

@@ -29,6 +29,7 @@ describe("settings", () => {
 			expect(connection.send).toHaveBeenLastCalledWith({
 				event: "getGlobalSettings",
 				context: connection.registrationParameters.pluginUUID,
+				id: expect.any(String),
 			} as GetGlobalSettings);
 
 			expect(Promise.race([settings, false])).resolves.toBe(false);

src/plugin/__tests__/settings.test.ts

@@ -78,6 +78,7 @@ describe("Action", () => {
 		expect(connection.send).toHaveBeenLastCalledWith<[GetSettings]>({
 			event: "getSettings",
 			context: action.id,
+			id: expect.any(String),
 		});
 
 		expect(Promise.race([settings, false])).resolves.toBe(false);