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-13
+
+### Added
+
+- Ephemeral Message 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

README.md

@@ -34,6 +34,11 @@ type Payload = {
   label: string;
   value: number;
 };
+// optional, only needed when you are planning to use the Ephemeral message p2p api.
+type EphemeralPayload = {
+  my_action: string;
+  my_argument: string;
+};
 ```
 
 Once you have a `Payload` type, you can declare the type of `window.webxdc` in
@@ -44,7 +49,7 @@ import { WebXdc } from "webxdc-types";
 
 declare global {
   interface Window {
-    webxdc: WebXdc<Payload>;
+    webxdc: WebXdc<Payload, EphemeralPayload>;
   }
 }
 ```
@@ -58,7 +63,7 @@ Now `window.webxdc` should be fully typed.
 <details>
 <summary> Usage in Typescript without payload typing </summary>
 
-Use this if you just want completions for the api, but not for the status update payloads, they will get the `any` type with this method.
+Use this if you just want completions only for the global API, but not for the status update and ephemeral message payloads. These will be filled with the generic `any` type.
 
 ```typescript
 import "webxdc-types/global";
@@ -90,11 +95,12 @@ You can use this to import the webxdc types when you need them to type your func
 
 ```js
 /**
- * @typedef {any} MyPayload
+ * @typedef {any} MyUpdatePayload
+ * @typedef {any} MyEphemeralPayload
  * @typedef {import('webxdc-types').XDCFile} XDCFile
- * @typedef {import('webxdc-types').ReceivedStatusUpdate<MyPayload>} ReceivedStatusUpdate
- * @typedef {import('webxdc-types').SendingStatusUpdate<MyPayload>} SendingStatusUpdate
- * @typedef {import('webxdc-types').Webxdc<MyPayload>} Webxdc
+ * @typedef {import('webxdc-types').ReceivedStatusUpdate<MyUpdatePayload, MyEphemeralPayload>} ReceivedStatusUpdate
+ * @typedef {import('webxdc-types').SendingStatusUpdate<MyUpdatePayload, MyEphemeralPayload>} SendingStatusUpdate
+ * @typedef {import('webxdc-types').Webxdc<MyUpdatePayload, MyEphemeralPayload>} Webxdc
  */
 // note that this does not set `window.webxdc` for you follow the steps below for that.
 ```
@@ -109,7 +115,7 @@ If you just want the api and not want to type your payloads you can import the t
 
 ### With typed payloads
 
-For this you need to create a `mytypes.d.ts` file declaring your payload type:
+For this you need to create a `mytypes.d.ts` file declaring your payload types:
 
 ```typescript
 import { WebXdc } from "webxdc-types";
@@ -120,9 +126,16 @@ type Payload = {
   value: number;
 };
 
+// optional, only needed when you are planning to use the Ephemeral message p2p api.
+// if you do not use it set it to `any`
+type EphemeralPayload = {
+  my_action: string;
+  my_argument: string;
+};
+
 declare global {
   interface Window {
-    webxdc: WebXdc<Payload>;
+    webxdc: WebXdc<Payload, EphemeralPayload>;
   }
 }
 ```

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,7 @@ type SendOptions =
       text: string;
     };
 
-interface Webxdc<T> {
+interface Webxdc<StatusPayload, EphemeralPayload = any> {
   /** 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 +74,37 @@ 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>;
+
+  /**
+   * Set a listener for _ephemeral_ status updates.
+   * Own status updates are not received.
+   * 
+   * @returns Promise that is resolved when the there is atleast one peer connected
+   */
+  setEphemeralUpdateListener(cb: (payload: EphemeralPayload) => void): Promise<void>;
+
   /**
    * @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 an ephemeral update to another peer.
+   * @param payload Data that can be serialized with `JSON.stringify`.
+   * 
+   * @returns A promise that resolves when a peer connection is established. Ephemeral messages can then be sent with `sendEphemeral`
+   */
+  sendEphemeralUpdate(payload: EphemeralPayload): Promise<void>;
+
   /**
    * Send a message with file, text or both to a chat.
    * Asks user to what Chat to send the message to.
@@ -116,4 +134,4 @@ interface Webxdc<T> {
   }): Promise<File[]>;
 }
 
-export { SendingStatusUpdate, ReceivedStatusUpdate, Webxdc, XDCFile };
+export { SendingStatusUpdate, ReceivedStatusUpdate, Webxdc, XDCFile };