@hussra/logos-proclaim 0.0.0-stage → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Bitfocus AS - Open Source
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# logos-proclaim
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Node module to communicate with the [Logos Proclaim](https://proclaim.logos.com/) presentation software through its
+[App Command](https://support.proclaim.logos.com/hc/en-us/articles/19864456647053-Proclaim-App-Command-API) and
+Local Wi-Fi APIs.
+
+```TypeScript
+import { ProclaimAPI } from '@hussra/logos-proclaim'
+
+const proclaim = new ProclaimAPI()
+await proclaim.configure('192.168.100.10', 'proclaim') // or just configure() if Proclaim is running on localhost
+```
+
+Status information is obtained from `proclaim.status` which has many properties, and can have event listeners registered
+on it to receive notice of status changes.
+
+```TypeScript
+proclaim.status.on('connected', ({data}) => {
+  console.log(`Are we connected? ${data}`)
+})
+```
+
+Look at the properties of the `ProclaimStatus` class for more details.
+
+The `proclaim.status.presentation` property will surface information about the on-air presentation (only while it is on air).
+
+The `log` event is used to provide a logging-framework-agnostic way for the library to emit log information.
+
+Commands using Proclaim's App Command API can be sent using `proclaim.sendAppCommand()` e.g.
+
+```TypeScript
+import { AppCommand } from '@hussra/logos-proclaim'
+
+await proclaim.sendAppCommand({command: AppCommand.GoOnAir})
+```
+
+or
+
+```TypeScript
+await proclaim.sendAppCommand({command: AppCommand.GoToSong, index: 1})
+```
+
+One command - not available via the App Command API but only through the Local Wi-Fi API - allows you to jump to a specific
+service item by ID, and slide within that service item. You will first need to find that service item's ID by digging into
+`proclaim.status.presentation`, then do something like:
+
+```TypeScript
+await proclaim.goToServiceItemAndSlide('abcdef12-3456-7890-abcd-ef1234567890', 2)
+```

package/dist/proclaim-api.d.ts

@@ -0,0 +1,111 @@
+import { ProclaimStatus } from './proclaim-status.js';
+import { IndexedAppCommand, SimpleAppCommand } from './proclaim-types.js';
+export * from './proclaim-types.js';
+export * from './proclaim-status.js';
+/**
+ * Encapsulate the Proclaim API connections
+ */
+export declare class ProclaimAPI {
+    #private;
+    /**
+     * The IP address of the computer where Proclaim is running
+     */
+    get ip(): string | undefined;
+    /**
+     * The password to use to connection to the App Command API
+     */
+    get password(): string | undefined;
+    /**
+     * Authentication is required for IPs other than 127.0.0.1
+     */
+    get authRequired(): boolean;
+    /**
+     * The status object representing the current state of the API connection and any on-air presentation
+     */
+    get status(): ProclaimStatus;
+    /**
+     * Config is valid if we have an IP address, and (unless IP is 127.0.0.1) we have a password specified
+     * @returns boolean
+     */
+    private configIsValid;
+    /**
+     * Configure this ProclaimAPI instance
+     * @param ip - IP address where Proclaim is running
+     * @param password - Proclaim local remote password - required if ip is other than 127.0.0.1
+     */
+    configure(ip?: string, password?: string): Promise<void>;
+    /**
+     * Add internal event listeners for ProclaimStatus events - these listeners respond
+     * to our own state changes triggering further internal actions
+     */
+    private addEventListeners;
+    /**
+     * Calculate status properties that depend on the currently live service item:
+     * itemIndex, itemTitle, itemKind, itemSlideCount, servicePart
+     * @param data - ID of live service item
+     */
+    private setItemProperties;
+    /**
+     * Initialise polling to check if Proclaim has gone on air - every 1 second
+     */
+    private initOnAirPolling;
+    /**
+     * Poll to see whether Proclaim has gone on air. If already on air, does nothing - going off
+     * air is detected by presentation status changes
+     */
+    private onAirPoll;
+    /**
+     * Load details of the on-air presentation
+     */
+    private loadPresentation;
+    /**
+     * Call /onair/statusChanged to get current presentation status, passing the current session ID, presentation
+     * local revision and step. If the details sent are all current, Proclaim will long-poll for up to a minute
+     * before responding.
+     */
+    private getPresentationStatus;
+    /**
+     * Get an auth token for the App Command API
+     */
+    private getAppCommandAPIAuthToken;
+    /**
+     * Refresh auth tokens for App Command and Local Wi-Fi APIs
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Send any App Command to Proclaim
+     * @param command - The App Command to send: see documentation at
+     *   https://support.proclaim.logos.com/hc/en-us/articles/19864456647053-Proclaim-App-Command-API
+     * @param index - For certain App Commands (annotated with an * at the API reference), the index to use (1-254)
+     *   e.g. service item number, slide number, verse number etc.
+     * @returns Whether the command was sent successfully
+     */
+    sendAppCommand(cmd: {
+        command: SimpleAppCommand;
+    } | {
+        command: IndexedAppCommand;
+        index: number;
+    }): Promise<boolean>;
+    /**
+     * Get an auth token for the Local Wi-Fi API
+     */
+    private getLocalWiFiRemoteAuthToken;
+    /**
+     * Jump to a specific service item by ID, and optionally a specific slide number
+     * @param itemId - ID of the service item to jump to
+     * @param slideIndex - slide number to jump to within that service item (0-based)
+     * @returns Whether the command was sent successfully
+     */
+    goToServiceItemAndSlide(itemId: string, slideIndex?: number): Promise<boolean>;
+    /**
+     * On being destroyed, clear the on-air polling interval
+     */
+    destroy(): void;
+    /**
+     * Sleep
+     * @param ms - number of milliseconds to sleep
+     * @returns Promise that will resolve after the specified time
+     */
+    private sleep;
+}
+//# sourceMappingURL=proclaim-api.d.ts.map

package/dist/proclaim-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proclaim-api.d.ts","sourceRoot":"","sources":["../src/proclaim-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EACN,iBAAiB,EAGjB,gBAAgB,EAKhB,MAAM,qBAAqB,CAAA;AAE5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AASpC;;GAEG;AACH,qBAAa,WAAW;;IAUvB;;OAEG;IACH,IAAI,EAAE,uBAEL;IAED;;OAEG;IACH,IAAI,QAAQ,uBAEX;IAED;;OAEG;IACH,IAAI,YAAY,YAEf;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,cAAc,CAE3B;IAED;;;OAGG;IACH,OAAO,CAAC,aAAa;IAYrB;;;;OAIG;IACG,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAmB9C;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAyEzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAgCzB;;OAEG;YACW,gBAAgB;IAO9B;;;OAGG;YACW,SAAS;IAgDvB;;OAEG;YACW,gBAAgB;IA6C9B;;;;OAIG;YACW,qBAAqB;IAmEnC;;OAEG;YACW,yBAAyB;IAsCvC;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAOhC;;;;;;;OAOG;IACG,cAAc,CACnB,GAAG,EAAE;QAAE,OAAO,EAAE,gBAAgB,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,iBAAiB,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAChF,OAAO,CAAC,OAAO,CAAC;IAiDnB;;OAEG;YACW,2BAA2B;IA2CzC;;;;;OAKG;IACG,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAsD/E;;OAEG;IACH,OAAO,IAAI,IAAI;IAMf;;;;OAIG;IACH,OAAO,CAAC,KAAK;CAGb"}