@pryv/socket.io 2.4.5 → 2.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pryv/socket.io",
-  "version": "2.4.5",
+  "version": "2.4.6",
   "description": "Extends `pryv` with Socket.IO transport",
   "keywords": [
     "Pryv",
@@ -19,6 +19,7 @@
   "license": "BSD-3-Clause",
   "author": "Pryv S.A. <info@pryv.com> (https://pryv.com)",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "dependencies": {
     "socket.io-client": "^4.5.1"
   }

package/src/index.d.ts

@@ -0,0 +1,84 @@
+import pryv from 'pryv';
+import { EventEmitter } from 'events';
+
+/**
+ * Extends a `pryv` instance with Socket.IO capabilities.
+ *
+ * Typical usage:
+ * ```ts
+ * import pryv from 'pryv';
+ * import extendPryvSocketIO from '@pryv/socket.io';
+ *
+ * extendPryvSocketIO(pryv);
+ *
+ * const connection = new pryv.Connection('https://token@user.pryv.me');
+ * await connection.socket.open();
+ * connection.socket.on('eventsChanged', (changes) => {
+ *   // ...
+ * });
+ * ```
+ */
+export default function extendPryvSocketIO(pryvLib: typeof pryv): void;
+
+declare module 'pryv' {
+  /**
+   * Socket.IO transport for a `Connection`.
+   *
+   * Use `connection.socket` to access the instance associated with a given
+   * `Connection`.
+   */
+  export class SocketIO extends EventEmitter {
+    constructor(connection: Connection);
+
+    /**
+     * Open the Socket.IO stream.
+     * @throws Error on connection failures
+     * @returns The same `SocketIO` instance once connected.
+     */
+    open(): Promise<SocketIO>;
+
+    /**
+     * Close the underlying socket connection.
+     */
+    close(): void;
+
+    /**
+     * Identical to `Connection.api()` but using the Socket.IO transport.
+     */
+    api<Calls extends APICall[] = APICall[]>(
+      apiCalls: Calls,
+      progress?: APICallProgressHandler
+    ): Promise<Array<TypedAPICallResult>>;
+
+    /**
+     * Listen to Socket.IO events emitted by the Pryv.io backend.
+     *
+     * Supported events:
+     * - `eventsChanged`
+     * - `streamsChanged`
+     * - `accessesChanged`
+     * - `disconnect`
+     * - `error`
+     */
+    on(
+      eventName:
+        | 'eventsChanged'
+        | 'streamsChanged'
+        | 'accessesChanged'
+        | 'disconnect'
+        | 'error',
+      listener: (...args: any[]) => void
+    ): this;
+  }
+
+  export class Connection {
+    /**
+     * Lazily created Socket.IO helper bound to this connection.
+     *
+     * Call `await connection.socket.open()` before using it.
+     */
+    get socket(): SocketIO;
+  }
+}
+
+