From f7bb6ae06e2ec27c7475246e69bdcc936f20edae Mon Sep 17 00:00:00 2001
From: dmc <david.mark.clements@gmail.com>
Date: Thu, 7 Mar 2024 02:43:21 +0100
Subject: [PATCH] document Pear.wakeups

---
 reference/api.md | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/reference/api.md b/reference/api.md
index 7655258..c5c5b6c 100644
--- a/reference/api.md
+++ b/reference/api.md
@@ -104,7 +104,7 @@ The Pear link of an application. Takes the form `pear://<key>/<data>`.
 In development, `pear://dev/<data>`.
 
 **References**
-* [Pear.config.link](#pearconfiglinkdata-string)
+* [Pear.config.linkData](#pearconfiglinkdata-string)
 * [`pear dev`](./cli.md)
 * [`pear run`](./cli.md)
 
@@ -362,7 +362,7 @@ will be waited upon until resolution before calling the next teardown handler.
 
 Restart the application.
 
-### `Pear.updates(listener <Async Function|Function>)`
+### `Pear.updates(listener <Async Function|Function>) => streamx.Readable`
 
 The `listener` function is called for every incoming update with an `update` object of the form:
 
@@ -381,6 +381,32 @@ The `listener` function is called for every incoming update with an `update` obj
   * `type` `<String>` - Operation type `update` or `delete`
   * `key` `<String>` - Drive key for a given updated file e.g. `/path/to/file.txt`
 
+Also returns a [`streamx`](https://github.com/mafintosh/streamx) `Readable`) stream.
+
+### `Pear.wakeups(listener <Async Function|Function>) => streamx.Readable`
+
+A wakeup occurs in the following cases:
+
+* when a trusted `pear://` link is clicked and the application for that link is already open
+* when used with `pear run --detached pear://<key>[/data]`
+
+The `listener` function is called for every incoming wakeup with a `wakeup` object of the form:
+
+```js
+{
+  type: 'pear/wakeup',
+  link: <String>,
+  data: <String>
+}
+```
+
+* `link` is the `pear://` link for the application receiving the wakeup
+* `data` is everything after the key in the `pear://` link - this would be `pathname` of a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) object but without the leading slash (`/`). Given `pear://8ts9yz9dtucxzwbxafygnjasqe9ti3dt3w7rm6sbiu8prmidacao/some/more/stuff` the `data` string would hold `some/more/stuff`.
+
+Also returns a [`streamx`](https://github.com/mafintosh/streamx) `Readable`) stream.
+
+
+
 
 ### `const win = new Pear.Window(entry <String>, options <Object>)`