feat: ephemeral peer channels

CHANGELOG.md

@@ -7,13 +7,23 @@ release date when you use `npm version` (see `README.md`).
 
 ## [Unreleased]
 
-## [1.0.1][] - 2023-10-19
+## [1.1.0] - 2023-04-22
+
+### Added
+
+- Realtime data API
+
+### Changed
+
+- clarify what `T` is
+
+## [1.0.1] - 2023-10-19
 
 ### Fixed
 
 - add dummy js files, because vite complained that it did not found the code, see #5
 
-## [1.0.0][] - 2023-10-11
+## [1.0.0] - 2023-10-11
 
 ### Added
 
@@ -24,20 +34,20 @@ release date when you use `npm version` (see `README.md`).
 
 - updated to the newest definitions from webxdc docs, as this repo should now become the source of truth for the typescript bindings. 
 
-## [0.1.0][] - 2022-07-18
+## [0.1.0] - 2022-07-18
 
 ### Changed
 
 - Fix import in README
 
-## [0.0.3][] - 2022-07-18
+## [0.0.3] - 2022-07-18
 
 Initial public release.
 
-[unreleased]: https://github.com/webxdc/webxdc-types/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/webxdc/webxdc-types/tree/v0.1.0
 
-
-[Unreleased]: https://github.com/webxdc/webxdc-types/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/webxdc/webxdc-types/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/webxdc/webxdc-types/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/webxdc/webxdc-types/compare/v1.0.0...v1.0.1
-[1.0.0]: https://github.com/webxdc/webxdc-types/tree/v1.0.0
+[1.0.0]: https://github.com/webxdc/webxdc-types/tree/v1.0.0
+[0.1.0]: https://github.com/webxdc/webxdc-types/tree/v0.1.0
+[0.0.3]: https://github.com/webxdc/webxdc-types/tree/v0.0.3

global.d.ts

@@ -1,6 +1,6 @@
 import { Webxdc } from "./webxdc";
 declare global {
   interface Window {
-    webxdc: Webxdc<any>;
+    webxdc: Webxdc<any, any>;
   }
 }

webxdc.d.ts

@@ -1,7 +1,7 @@
-type SendingStatusUpdate<T> = {
+type SendingStatusUpdate<PayloadType> = {
   /** the payload, deserialized json:
    * any javascript primitive, array or object. */
-  payload: T;
+  payload: PayloadType;
   /** optional, short, informational message that will be added to the chat,
    * eg. "Alice voted" or "Bob scored 123 in MyGame";
    * usually only one line of text is shown,
@@ -16,9 +16,9 @@ type SendingStatusUpdate<T> = {
   summary?: string;
 };
 
-type ReceivedStatusUpdate<T> = {
+type ReceivedStatusUpdate<PayloadType> = {
   /** the payload, deserialized json */
-  payload: T;
+  payload: PayloadType;
   /** the serial number of this update. Serials are larger than 0 and newer serials have higher numbers */
   serial: number;
   /** the maximum serial currently known */
@@ -60,7 +60,27 @@ type SendOptions =
       text: string;
     };
 
-interface Webxdc<T> {
+/**
+ * A listener for realtime data.
+ */
+export class RealtimeListener {
+  listener: (data: Uint8Array) => void
+  active: boolean
+  trashed: boolean
+
+  /* Whether the realtime channel was left */
+  is_trashed(): boolean
+  /* Receive data from the realtime channel */
+  receive(data: Uint8Array): void
+  /* Set a listener for the realtime channel */
+  setListener(listener: (data: Uint8Array) => void): void
+  /* Send data over the realtime channel */
+  send(data: Uint8Array): void
+  /* Leave the realtime channel */
+  leave(): void
+}
+
+interface Webxdc<StatusPayload> {
   /** Returns the peer's own address.
    *  This is esp. useful if you want to differ between different peers - just send the address along with the payload,
    *  and, if needed, compare the payload addresses against selfAddr() later on. */
@@ -74,19 +94,31 @@ interface Webxdc<T> {
    * @returns promise that resolves when the listener has processed all the update messages known at the time when `setUpdateListener` was called.
    * */
   setUpdateListener(
-    cb: (statusUpdate: ReceivedStatusUpdate<T>) => void,
+    cb: (statusUpdate: ReceivedStatusUpdate<StatusPayload>) => void,
     serial?: number
   ): Promise<void>;
+
+  /**
+   * Join a realtime channel.
+   */
+  joinRealtimeChannel(): RealtimeListener;
+
   /**
    * @deprecated See {@link setUpdateListener|`setUpdateListener()`}.
    */
-  getAllUpdates(): Promise<ReceivedStatusUpdate<T>[]>;
+  getAllUpdates(): Promise<ReceivedStatusUpdate<StatusPayload>[]>;
   /**
    * Webxdc are usually shared in a chat and run independently on each peer. To get a shared status, the peers use sendUpdate() to send updates to each other.
    * @param update status update to send
    * @param description short, human-readable description what this update is about. this is shown eg. as a fallback text in an email program.
    */
-  sendUpdate(update: SendingStatusUpdate<T>, description: string): void;
+  sendUpdate(update: SendingStatusUpdate<StatusPayload>, description: string): void;
+
+  /**
+   * Send realtime data.
+   */
+  sendRealtimeData(payload: Uint8Array): void;
+
   /**
    * Send a message with file, text or both to a chat.
    * Asks user to what Chat to send the message to.