@companion-surface/base 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.3.0](https://github.com/bitfocus/companion-surface-api/compare/companion-surface-base-v0.2.0...companion-surface-base-v0.3.0) (2025-10-28)
+
+
+### Features
+
+* firmware update check api ([080264a](https://github.com/bitfocus/companion-surface-api/commit/080264a4fd3f5f81a936810b030f5d42672f26de))
+* implement firmware update check ([ffa137b](https://github.com/bitfocus/companion-surface-api/commit/ffa137bc65bc046bcbdc7f392746d8f0ce598e69))
+* remote surfaces api ([3f6a4b5](https://github.com/bitfocus/companion-surface-api/commit/3f6a4b5009971f8f301bdacdf8d12f2b9dfdbd02))
+* remote surfaces detection ([0a4b5eb](https://github.com/bitfocus/companion-surface-api/commit/0a4b5eb8deaa540ce40c2613ec4e4e37dcefde97))
+
+
+### Bug Fixes
+
+* remote surfaces location ([0840197](https://github.com/bitfocus/companion-surface-api/commit/0840197468c2aadd32ab77277ac57332c5c9c28c))
+
 ## [0.2.0](https://github.com/bitfocus/companion-surface-api/compare/companion-surface-base-v0.1.5...companion-surface-base-v0.2.0) (2025-10-23)
 
 

package/dist/surface-api/detection.d.ts

@@ -0,0 +1,22 @@
+import type EventEmitter from 'node:events';
+import type { DiscoveredSurfaceInfo } from './plugin.js';
+export interface SurfacePluginDetectionEvents<TInfo> {
+    surfacesAdded: [surfaceInfos: DiscoveredSurfaceInfo<TInfo>[]];
+}
+/**
+ * For some plugins which only support using a builtin detection mechanism, this can be used to provide the detection info
+ */
+export interface SurfacePluginDetection<TInfo> extends EventEmitter<SurfacePluginDetectionEvents<TInfo>> {
+    /**
+     * Trigger this plugin to perform a scan for any connected surfaces.
+     * This is used when the user triggers a scan, so should refresh any caches when possible
+     */
+    triggerScan(): Promise<void>;
+    /**
+     * When a surface is discovered, but the application has chosen not to open it, this function is called to inform the detection mechanism
+     * You can use this to cleanup any resources/handles for this surface, as it will not be used further
+     * @param surfaceInfo The info about the surface which was rejected
+     */
+    rejectSurface(surfaceInfo: DiscoveredSurfaceInfo<TInfo>): void;
+}
+//# sourceMappingURL=detection.d.ts.map

package/dist/surface-api/detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../src/surface-api/detection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,MAAM,WAAW,4BAA4B,CAAC,KAAK;IAClD,aAAa,EAAE,CAAC,YAAY,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;CAE7D;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,CAAE,SAAQ,YAAY,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC;IACvG;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5B;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;CAC9D"}

package/dist/surface-api/detection.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=detection.js.map

package/dist/surface-api/detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.js","sourceRoot":"","sources":["../../src/surface-api/detection.ts"],"names":[],"mappings":""}

package/dist/surface-api/firmware.d.ts

@@ -0,0 +1,14 @@
+export interface SurfaceFirmwareUpdateInfo {
+    /**
+     * URL to direct the user towards for performing the update
+     */
+    updateUrl: string;
+}
+export interface SurfaceFirmwareUpdateCache {
+    /**
+     * Fetch a json resource from the given URL. Calls will be cached between different surfaces
+     * @param url
+     */
+    fetchJson(url: string): Promise<any>;
+}
+//# sourceMappingURL=firmware.d.ts.map

package/dist/surface-api/firmware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firmware.d.ts","sourceRoot":"","sources":["../../src/surface-api/firmware.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACzC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;CACpC"}

package/dist/surface-api/firmware.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=firmware.js.map

package/dist/surface-api/firmware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firmware.js","sourceRoot":"","sources":["../../src/surface-api/firmware.ts"],"names":[],"mappings":""}

package/dist/surface-api/index.d.ts

@@ -1,7 +1,11 @@
 export * from './cards.js';
 export * from './context.js';
+export * from './detection.js';
+export * from './firmware.js';
+export * from './input.js';
 export * from './instance.js';
 export * from './pincode.js';
 export * from './plugin.js';
+export * from './remote.js';
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/surface-api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/surface-api/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/surface-api/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/dist/surface-api/index.js

@@ -1,7 +1,11 @@
 export * from './cards.js';
 export * from './context.js';
+export * from './detection.js';
+export * from './firmware.js';
+export * from './input.js';
 export * from './instance.js';
 export * from './pincode.js';
 export * from './plugin.js';
+export * from './remote.js';
 export * from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/surface-api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/surface-api/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/surface-api/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/dist/surface-api/input.d.ts

@@ -0,0 +1,156 @@
+export type InputValue = number | string | boolean;
+export type OptionsObject = {
+    [key: string]: InputValue | undefined;
+};
+export type SomeCompanionInputField = CompanionInputFieldStaticText | CompanionInputFieldTextInput | CompanionInputFieldDropdown | CompanionInputFieldNumber | CompanionInputFieldCheckbox;
+/**
+ * The common properties for an input field
+ */
+export interface CompanionInputFieldBase {
+    /** The unique id of this input field within the input group */
+    id: string;
+    /** The type of this input field */
+    type: 'static-text' | 'textinput' | 'dropdown' | 'number' | 'checkbox';
+    /** The label of the field */
+    label: string;
+    /** A hover tooltip for this field */
+    tooltip?: string;
+    /** A longer description/summary/notes for this field */
+    description?: string;
+    /**
+     * A companion expression to check whether this input should be visible, based on the current options selections within the input group
+     *
+     * This is the same syntax as other expressions written inside of Comapnion.
+     * You can access a value of the current options using `$(options:some_field_id)`.
+     * This does not support the `isVisibleData` property, let us know if you need this.
+     */
+    isVisibleExpression?: string;
+}
+/**
+ * A static un-editable line of text
+ *
+ * ### Example
+ * ```js
+ * {
+ * 	id: 'important-line',
+ * 	type: 'static-text',
+ * 	label: 'Important info',
+ * 	value: 'Some message here'
+ * }
+ * ```
+ */
+export interface CompanionInputFieldStaticText extends CompanionInputFieldBase {
+    type: 'static-text';
+    /** The text to show */
+    value: string;
+}
+/**
+ * A basic text input field
+ *
+ * ### Example
+ * ```js
+ * {
+ * 	id: 'val',
+ * 	type: 'textinput',
+ * 	label: 'Provide name',
+ * 	'default': 'Bob'
+ * }
+ * ```
+ */
+export interface CompanionInputFieldTextInput extends CompanionInputFieldBase {
+    type: 'textinput';
+    /**
+     * The default text value
+     */
+    default?: string;
+    /**
+     * A regex to use to inform the user if the current input is valid.
+     * Note: values may not conform to this, it is a visual hint only
+     */
+    regex?: string;
+}
+export type DropdownChoiceId = string | number;
+/**
+ * An option for a dropdown input
+ *
+ * Available for actions/feedbacks/config
+ */
+export interface DropdownChoice {
+    /** Value of the option */
+    id: DropdownChoiceId;
+    /** Label to show to users */
+    label: string;
+}
+/**
+ * A dropdown input field
+ *
+ * ### Example
+ * ```js
+ * {
+ * 	id: 'val',
+ * 	type: 'dropdown',
+ * 	label: 'Select name',
+ * 	choices: [
+ * 		{ id: 'bob', label: 'Bob' },
+ * 		{ id: 'sally', label: 'Sally' },
+ * 	],
+ * 	default: 'bob'
+ * }
+ * ```
+ */
+export interface CompanionInputFieldDropdown extends CompanionInputFieldBase {
+    type: 'dropdown';
+    /** The possible choices */
+    choices: DropdownChoice[];
+    /** The default selected value */
+    default: DropdownChoiceId;
+}
+/**
+ * A checkbox input field
+ *
+ * ### Example
+ * ```js
+ * {
+ * 	id: 'doit',
+ * 	type: 'checkbox',
+ * 	label: 'Do the thing',
+ * 	default: true
+ * }
+ * ```
+ */
+export interface CompanionInputFieldCheckbox extends CompanionInputFieldBase {
+    type: 'checkbox';
+    /** The default value */
+    default: boolean;
+}
+/**
+ * A number input field
+ *
+ * ### Example
+ * ```js
+ * {
+ * 	id: 'size',
+ * 	type: 'number',
+ * 	label: 'Target size',
+ * 	default: 50,
+ * 	min: 0,
+ * 	max: 100
+ * }
+ * ```
+ */
+export interface CompanionInputFieldNumber extends CompanionInputFieldBase {
+    type: 'number';
+    /** The default value */
+    default: number;
+    /**
+     * The minimum value to allow
+     * Note: values may not conform to this, it is a visual hint only
+     */
+    min: number;
+    /**
+     * The maximum value to allow
+     * Note: values may not conform to this, it is a visual hint only
+     */
+    max: number;
+}
+//# sourceMappingURL=input.d.ts.map

package/dist/surface-api/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/surface-api/input.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAElD,MAAM,MAAM,aAAa,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;CAAE,CAAA;AAErE,MAAM,MAAM,uBAAuB,GAChC,6BAA6B,GAC7B,4BAA4B,GAC5B,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,CAAA;AAE9B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,IAAI,EAAE,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAA;IACtE,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC7E,IAAI,EAAE,aAAa,CAAA;IACnB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC5E,IAAI,EAAE,WAAW,CAAA;IACjB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAA;AAC9C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,0BAA0B;IAC1B,EAAE,EAAE,gBAAgB,CAAA;IACpB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC3E,IAAI,EAAE,UAAU,CAAA;IAEhB,2BAA2B;IAC3B,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB,iCAAiC;IACjC,OAAO,EAAE,gBAAgB,CAAA;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC3E,IAAI,EAAE,UAAU,CAAA;IAChB,wBAAwB;IACxB,OAAO,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE,IAAI,EAAE,QAAQ,CAAA;IAEd,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAA;CACX"}

package/dist/surface-api/input.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=input.js.map

package/dist/surface-api/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../src/surface-api/input.ts"],"names":[],"mappings":""}

package/dist/surface-api/instance.d.ts

@@ -1,4 +1,5 @@
 import type { CardGenerator } from './cards.js';
+import type { SurfaceFirmwareUpdateCache, SurfaceFirmwareUpdateInfo } from './firmware.js';
 import type { SurfaceDrawProps, SurfaceId } from './types.js';
 export interface SurfaceInstance {
     /**
@@ -48,5 +49,11 @@ export interface SurfaceInstance {
      * @param cardGenerator Card generator to create the status image(s)
      */
     showStatus(signal: AbortSignal, cardGenerator: CardGenerator, statusMessage: string): Promise<void>;
+    /**
+     * Check for firmware updates for this surface
+     * @param versionsCache Cache object to assist with caching any api calls needed to determine latest versions
+     * @returns Firmware update info, or null if no update is available
+     */
+    checkForFirmwareUpdates?(versionsCache: SurfaceFirmwareUpdateCache): Promise<SurfaceFirmwareUpdateInfo | null>;
 }
 //# sourceMappingURL=instance.d.ts.map

package/dist/surface-api/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/surface-api/instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE7D,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAItB;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7C;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErE,eAAe,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAAA;IAEhD,gBAAgB,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhE;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnG"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/surface-api/instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA;AAC1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE7D,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAItB;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7C;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErE,eAAe,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAAA;IAEhD,gBAAgB,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhE;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnG;;;;OAIG;IACH,uBAAuB,CAAC,CAAC,aAAa,EAAE,0BAA0B,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAA;CAC9G"}

package/dist/surface-api/plugin.d.ts

@@ -1,31 +1,7 @@
-import type EventEmitter from 'node:events';
-import type { HIDDevice, OpenSurfaceResult, SurfaceId } from './types.js';
-import { SurfaceContext } from './context.js';
-export interface DiscoveredSurfaceInfo<TInfo> {
-    surfaceId: string;
-    description: string;
-    pluginInfo: TInfo;
-}
-export interface SurfacePluginDetectionEvents<TInfo> {
-    surfacesAdded: [surfaceInfos: DiscoveredSurfaceInfo<TInfo>[]];
-    surfacesRemoved: [surfaceIds: SurfaceId[]];
-}
-/**
- * For some plugins which only support using a builtin detection mechanism, this can be used to provide the detection info
- */
-export interface SurfacePluginDetection<TInfo> extends EventEmitter<SurfacePluginDetectionEvents<TInfo>> {
-    /**
-     * Trigger this plugin to perform a scan for any connected surfaces.
-     * This is used when the user triggers a scan, so should refresh any caches when possible
-     */
-    triggerScan(): Promise<void>;
-    /**
-     * When a surface is discovered, but the application has chosen not to open it, this function is called to inform the detection mechanism
-     * You can use this to cleanup any resources/handles for this surface, as it will not be used further
-     * @param surfaceInfo The info about the surface which was rejected
-     */
-    rejectSurface(surfaceInfo: DiscoveredSurfaceInfo<TInfo>): void;
-}
+import type { HIDDevice, OpenSurfaceResult } from './types.js';
+import type { SurfaceContext } from './context.js';
+import type { SurfacePluginDetection } from './detection.js';
+import { SurfacePluginRemote } from './remote.js';
 /**
  * The base SurfacePlugin interface, for all surface plugins
  */
@@ -38,6 +14,13 @@ export interface SurfacePlugin<TInfo> {
      * Note: it is important that no events are emitted from this until after init() has been invoked, or they will be lost
      */
     readonly detection?: SurfacePluginDetection<TInfo>;
+    /**
+     * Some plugins can make connections to IP/cloud based surfaces
+     * In this case, this property should be set to an instance of SurfacePluginRemote
+     *
+     * Note: it is important that no events are emitted from this until after init() has been invoked, or they will be lost
+     */
+    readonly remote?: SurfacePluginRemote<TInfo>;
     /**
      * Initialize the plugin
      *
@@ -72,4 +55,9 @@ export interface SurfacePlugin<TInfo> {
      */
     openSurface: (surfaceId: string, pluginInfo: TInfo, context: SurfaceContext) => Promise<OpenSurfaceResult>;
 }
+export interface DiscoveredSurfaceInfo<TInfo> {
+    surfaceId: string;
+    description: string;
+    pluginInfo: TInfo;
+}
 //# sourceMappingURL=plugin.d.ts.map

package/dist/surface-api/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/surface-api/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE7C,MAAM,WAAW,qBAAqB,CAAC,KAAK;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,KAAK,CAAA;CACjB;AAED,MAAM,WAAW,4BAA4B,CAAC,KAAK;IAClD,aAAa,EAAE,CAAC,YAAY,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC7D,eAAe,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,CAAC,CAAA;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,CAAE,SAAQ,YAAY,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC;IACvG;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5B;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,KAAK,CAAC,CAAA;IAElD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAExB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,qBAAqB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;IAEnF;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAE/D;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAC1G"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/surface-api/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,KAAK,CAAC,CAAA;IAElD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAA;IAE5C;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAExB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,qBAAqB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;IAEnF;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAE/D;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAC1G;AAED,MAAM,WAAW,qBAAqB,CAAC,KAAK;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,KAAK,CAAA;CACjB"}

package/dist/surface-api/remote.d.ts

@@ -0,0 +1,64 @@
+import type EventEmitter from 'node:events';
+import type { OptionsObject, SomeCompanionInputField } from './input.js';
+import type { RemoteSurfaceConnectionInfo } from './types.js';
+import type { DiscoveredSurfaceInfo } from './plugin.js';
+export interface SurfacePluginRemoteEvents<TInfo> {
+    surfacesConnected: [surfaceInfos: DiscoveredSurfaceInfo<TInfo>[]];
+    /**
+     * Fired when surface discovery detects new surfaces
+     * This is used as suggestions in the ui of remote surfaces the user can setup
+     */
+    connectionsFound: [connectionInfos: DiscoveredRemoteSurfaceInfo[]];
+    /**
+     * Fired when previously detected surfaces are forgotten
+     * This is the opposite of connectionsFound, to forget any connections which are no longer available
+     */
+    connectionsForgotten: [connectionIds: string[]];
+}
+/**
+ * For some plugins which only support using a builtin detection mechanism, this can be used to provide the detection info
+ */
+export interface SurfacePluginRemote<TInfo> extends EventEmitter<SurfacePluginRemoteEvents<TInfo>> {
+    /**
+     * Get any configuration fields needed for configuring a remote connection
+     *
+     * Note: This gets called once during plugin initialisation. Changes made after this will not be detected
+     */
+    readonly configFields: SomeCompanionInputField[];
+    /**
+     * Setup one or more connections to remote surfaces
+     * @param connectionInfos Info about the connections to add
+     */
+    startConnections(connectionInfos: RemoteSurfaceConnectionInfo[]): Promise<void>;
+    /**
+     * Stop one or more connections to remote surfaces
+     * @param connectionIds Ids of the connections to remove
+     */
+    stopConnections(connectionIds: string[]): Promise<void>;
+    /**
+     * When a surface is discovered, but the application has chosen not to open it, this function is called to inform the detection mechanism
+     * You can use this to cleanup any resources/handles for this surface, as it will not be used further
+     * @param surfaceInfo The info about the surface which was rejected
+     */
+    rejectSurface(surfaceInfo: DiscoveredSurfaceInfo<TInfo>): void;
+}
+export interface DiscoveredRemoteSurfaceInfo {
+    /**
+     * A unique id. This is used to identify the connection for updates and being forgotten
+     */
+    id: string;
+    /**
+     * A user friendly name for the connection. Such as the hostname or user chosen name
+     */
+    displayName: string;
+    /**
+     * A secondary description for the connection. Such as the model or device type
+     */
+    description: string;
+    /**
+     * The configuration object to use for connecting to this remote surface.
+     * This should match the schema defined with `configFields`, as once added it will be user editable with those fields
+     */
+    config: OptionsObject;
+}
+//# sourceMappingURL=remote.d.ts.map

package/dist/surface-api/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/surface-api/remote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,MAAM,WAAW,yBAAyB,CAAC,KAAK;IAC/C,iBAAiB,EAAE,CAAC,YAAY,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAGjE;;;OAGG;IACH,gBAAgB,EAAE,CAAC,eAAe,EAAE,2BAA2B,EAAE,CAAC,CAAA;IAClE;;;OAGG;IACH,oBAAoB,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAA;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK,CAAE,SAAQ,YAAY,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC;IACjG;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,uBAAuB,EAAE,CAAA;IAEhD;;;OAGG;IACH,gBAAgB,CAAC,eAAe,EAAE,2BAA2B,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/E;;;OAGG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvD;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;CAC9D;AAED,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAKnB;;;OAGG;IACH,MAAM,EAAE,aAAa,CAAA;CACrB"}

package/dist/surface-api/remote.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=remote.js.map

package/dist/surface-api/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../../src/surface-api/remote.ts"],"names":[],"mappings":""}

package/dist/surface-api/types.d.ts

@@ -1,6 +1,7 @@
 import type { SurfacePincodeMap } from './pincode.js';
 import type { SurfaceInstance } from './instance.js';
 import type { SurfaceSchemaLayoutDefinition } from '../../generated/surface-layout.d.ts';
+import type { OptionsObject } from './input.js';
 /**
  * A representation of a HID device
  * A simplified form of the HIDDevice from node-hid
@@ -52,10 +53,10 @@ export interface SurfaceRegisterProps {
      * If the surface supports pincode entry, this is the desired arrangement of the pin entry buttons
      */
     pincodeMap: SurfacePincodeMap | null;
-}
-export interface SurfaceRegisterPropsComplete extends SurfaceRegisterProps {
-    gridSize: GridSize;
-    fallbackBitmapSize: number;
+    /**
+     * A user facing location string for the surface
+     */
+    location: string | null;
 }
 export interface OpenSurfaceResult {
     surface: SurfaceInstance;
@@ -82,4 +83,8 @@ export interface GridSize {
     rows: number;
     columns: number;
 }
+export interface RemoteSurfaceConnectionInfo {
+    connectionId: string;
+    config: OptionsObject;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/surface-api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/surface-api/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAA;AAExF;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAC9B,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AACD,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,aAAa,EAAE,6BAA6B,CAAA;IAC5C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,oBAAoB,GAAG,qBAAqB,CAAC,CAAA;IACvE;;OAEG;IACH,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,4BAA6B,SAAQ,oBAAoB;IACzE,QAAQ,EAAE,QAAQ,CAAA;IAClB,kBAAkB,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,eAAe,CAAA;IACxB,aAAa,EAAE,oBAAoB,CAAA;CACnC;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/surface-api/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAA;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAC9B,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AACD,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,aAAa,EAAE,6BAA6B,CAAA;IAC5C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,oBAAoB,GAAG,qBAAqB,CAAC,CAAA;IACvE;;OAEG;IACH,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAEpC;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,eAAe,CAAA;IACxB,aAAa,EAAE,oBAAoB,CAAA;CACnC;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,2BAA2B;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,aAAa,CAAA;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-surface/base",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "repository": "https://github.com/bitfocus/companion-surface-api",
@@ -18,7 +18,7 @@
     "docs:html": "typedoc --tsconfig tsconfig.build.json --entryPoints src/main.ts --excludePrivate --theme default --out docs"
   },
   "engines": {
-    "node": "^22.14"
+    "node": "^22.21"
   },
   "files": [
     "README.md",