@streamorchard/grapevine 0.1.1 → 0.3.0

package/PROTOCOL.md

@@ -10,6 +10,7 @@ Version 1. How desktop apps on the same computer find each other, pair, and talk
 - [Errors](#errors)
 - [Capabilities](#capabilities)
 - [Versions](#versions)
+- [Renaming an app](#renaming-an-app)
 - [Compatibility](#compatibility)
 - [Security](#security)
 
@@ -31,7 +32,7 @@ Every app has a **slug** (`a-z`, `0-9` and `-`, up to 40 characters, starting wi
 - A socket left by a crash answers nothing (`ECONNREFUSED`): its app deletes it and listens again when it starts. If something does answer, another copy of the app is running, and the new copy doesn't start its link.
 - An app only listens, and only looks for others, while at least one of its Connected apps switches is on.
 
-**Who connects.** Of two apps, the one whose id sorts first (plain string order) connects; the other waits for it. So a pair never opens two connections. If they ever do, both keep the connection opened by the app whose id sorts first and close the other with `link.bye { reason: "duplicate" }`.
+**Who connects.** Of two apps, the one whose slug sorts first (plain string order) connects; the other waits for it. So a pair never opens two connections. If they ever do, both keep the connection opened by the app whose slug sorts first and close the other with `link.bye { reason: "duplicate" }`. It's the slug, not the id, because an app's id can change (see [Renaming an app](#renaming-an-app)) and its socket's name doesn't.
 
 ## Messages
 
@@ -61,6 +62,7 @@ The connecting app sends `link.hello` first:
     "protocol": { "min": 1, "max": 1 },
     "app": {
       "id": "com.glowingpear.streammultiview",
+      "formerIds": [],
       "slug": "stream-multiview",
       "name": "Stream Multiview",
       "version": "0.4.0",
@@ -79,6 +81,7 @@ The connecting app sends `link.hello` first:
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `protocol`                            | The range of protocol versions it speaks                                                                                                      |
 | `app.id`                              | Its install id: lowercase letters, digits, dots and dashes, like `com.example.app` (3–100 characters)                                         |
+| `app.formerIds`                       | The ids it had before a rename, up to 10. Always sent: `[]` until the app is renamed                                                          |
 | `app.slug`, `app.name`, `app.version` | Required. `summary` (up to 300 characters), `icon` (a PNG data URL, up to 256 KB), `homepage` and `download` (`https` addresses) are optional |
 | `capabilities`                        | For each capability, the versions it `provides` and `uses`, as `"major.minor"`                                                                |
 | `auth.nonce`                          | 32 random bytes, base64, new for every connection                                                                                             |
@@ -88,12 +91,13 @@ The listening app checks it, in this order:
 
 1. A hello that doesn't fit the table gets `-32602` with `data.problems` (a list of strings), and the connection closes.
 2. No protocol version in both ranges: `-32003` with `data.protocol` (its own range), and close.
-3. Its switch for that app is off: `-32005`, and close.
+3. Its switch for that app is off: `-32005`, and close. The app is known by `app.id` or any of `app.formerIds`, and the switch counts under any of them.
 4. **Pairing.**
    - `pair: true` and it has no key for that app: it makes a new 32-byte random key `K`.
    - `pair: true` but it still has a key: `-32001` with `data: { reason: "pair-again", keyHeldBy: "listener" }`, and close. It accepts a new pairing only once its user presses **Pair again**, which deletes its key.
    - `pair: false` and it has no key: `-32001` with `data: { reason: "pair-again", keyHeldBy: "connector" }`, and close. The connecting app's user presses **Pair again** there.
    - Otherwise `K` is the key it has.
+   - "Has a key" means one filed under `app.id` or any of `app.formerIds` (or a former id its own known-apps list gives that app).
 5. It replies:
 
 ```json
@@ -107,7 +111,7 @@ The listening app checks it, in this order:
 
 The connecting app checks the reply:
 
-- its `app.id` is the app it meant to connect to;
+- its `app.id`, or one of its `app.formerIds`, is the app it meant to connect to;
 - it speaks the `protocol` chosen;
 - the `proof` matches its key, or the `key` it was just given when pairing.
 
@@ -177,7 +181,8 @@ A capability is a named feature one app provides and others use, defined by a JS
 | ----------- | ----------------------------------------------------------------- |
 | `Timestamp` | ISO 8601, in UTC                                                  |
 | `Platform`  | A streaming site: `kick`, `twitch`, `youtube`, or one added later |
-| `Channel`   | `{ platform, slug, name? }`                                       |
+| `Channel`   | `{ platform, slug, name?, avatar? }`                              |
+| `Image`     | A picture's `https` address, as the site gives it                 |
 | `Account`   | `{ platform, user }`: the username only, never a token or cookie  |
 | `Progress`  | `{ done, total, unit }`, where `unit` is `minutes` for now        |
 
@@ -190,14 +195,22 @@ A capability is a named feature one app provides and others use, defined by a JS
 
 ### `drops.farming` 1.0
 
-What a drops app is farming. Provided by Pear Drops.
+What a drops app is farming, with enough for another app to show it, in a top-bar widget say. Provided by Pear Drops.
 
-| Field     |                                                                                                                            |
-| --------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `state`   | `farming` (its player is watching a stream for drop credit), `waiting`, `paused`, `done`, `signed-out`, or one added later |
-| `account` | The account it farms for, or `null`                                                                                        |
-| `channel` | The stream it's watching while `farming`, else `null`                                                                      |
-| `drop`    | `{ campaign, category, progress }` while farming, else `null`                                                              |
+| Field          |                                                                                                                                                                    |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `state`        | `farming` (its player is watching a stream for drop credit), `waiting`, `paused`, `done`, `signed-out`, or one added later                                         |
+| `account`      | The account it farms for, or `null`                                                                                                                                |
+| `channel`      | The channel it's watching while `farming` (with its `avatar`, optional), else `null`                                                                               |
+| `stream`       | Optional, while farming: `{ title?, viewers? }`                                                                                                                    |
+| `drop`         | While farming, `{ campaign, category, progress }`, else `null`. Optional extras below                                                                              |
+| `drop.image`   | The category's picture                                                                                                                                             |
+| `drop.endsAt`  | When the drop ends                                                                                                                                                 |
+| `drop.rewards` | `{ claimed, total }`                                                                                                                                               |
+| `drop.next`    | The reward being worked towards: `{ name, image?, required, unlocksAt }`, where `required` is minutes and `unlocksAt` is when it should unlock at the current rate |
+| `drop.doneAt`  | When every reward should be earned at the current rate, or `null`                                                                                                  |
+
+`drops.farming.show {}` asks the drops app to bring its window to the front, for a click on that widget. It replies `{ shown }`.
 
 ### `players` 1.0
 
@@ -248,6 +261,16 @@ After the hello, each app tells its user one of:
 
 The releases come from the known-apps list (`src/known-apps.js`): `firstRelease` maps `"<capability>@<major>.<minor>"` and `"protocol@<n>"` to the first release of that app that had it.
 
+## Renaming an app
+
+An app's id can change, say from `com.glowingpear.streammultiview` to `com.streamorchard.streammultiview`. Apps paired with it under the old id carry on without pairing again:
+
+1. **The renamed app lists its old id in its hello:** `"formerIds": ["com.glowingpear.streammultiview"]`. That's the only change it needs.
+2. **Other apps find their key and their switch under any of its ids.** An app whose Grapevine predates the rename still knows it by the old id, and keeps working.
+3. **The known-apps list gets the new id,** with the old one in its own `formerIds`. An app updated to it shows the new id, finds what was saved under the old one, and can move its own settings across.
+
+Claiming a former id only says where to look for a key. The app still has to prove it holds that key, so it can't take over another app's pairing.
+
 ## Security
 
 **Who can connect:**

package/README.md

@@ -53,12 +53,29 @@ const link = createLink({
 
 await link.start();
 
-// Tell every app that subscribed. seq and at are added for you.
+// Tell every app that subscribed. seq and at are added for you, and the last one also answers
+// drops.farming.get. Everything past progress is optional: it's what a widget would show.
 link.publish('drops.farming.changed', {
   state: 'farming',
   account: { platform: 'kick', user: 'pearfan' },
-  channel: { platform: 'kick', slug: 'pixelpear' },
-  drop: null,
+  channel: { platform: 'kick', slug: 'pixelpear', name: 'PixelPear', avatar: 'https://files.kick.com/…/pixelpear.webp' },
+  stream: { title: 'Neon Rush ranked, chill vibes', viewers: 1240 },
+  drop: {
+    campaign: 'Neon Rush Launch Week',
+    category: 'Neon Rush',
+    progress: { done: 48, total: 120, unit: 'minutes' },
+    image: 'https://files.kick.com/…/neon-rush.webp',
+    endsAt: '2026-10-21T18:00:00Z',
+    rewards: { claimed: 1, total: 3 },
+    next: { name: 'Hype Rocket Emote', required: 60, unlocksAt: '2026-10-18T09:24:00Z' },
+    doneAt: '2026-10-18T10:24:00Z',
+  },
+});
+
+// A click on another app's widget asks to see Pear Drops.
+link.handle('drops.farming.show', () => {
+  mainWindow.show();
+  return { shown: true };
 });
 
 // Hear what the other apps provide.
@@ -69,6 +86,10 @@ link.on('event', (fromAppId, name, params) => {
 // Ask one of them something.
 const players = await link.request('com.glowingpear.streammultiview', 'players.get');
 
+// On the other side, an app showing a farming widget (Stream Multiview, say):
+//   link.on('event', (from, name, f) => name === 'drops.farming.changed' && drawWidget(f));
+//   widget.onclick = () => link.request('com.streamorchard.peardrops', 'drops.farming.show');
+
 // When a Connected apps switch changes:
 link.refresh();
 
@@ -92,6 +113,7 @@ Editors suggest every event's fields and underline mistakes, in plain JavaScript
 | `keyHeldBy`                           | For `pair-again`: `us` means show **Pair again** here, `them` means it's pressed in the other app          |
 | `version`, `report.text`              | While connected: its version, and "Works" or what's missing ("update Pear Drops to 0.1.7 or later")        |
 | `pairedAt`, `keysEncrypted`           | When they paired, and whether keys are stored encrypted                                                    |
+| `formerIds`                           | Ids the app had before a rename                                                                            |
 
 Two calls go with buttons on the card:
 
@@ -122,10 +144,10 @@ Example messages for every capability version, good and bad, are in `@streamorch
 
 ## Capabilities
 
-| Capability          | Provided by      | What it says                                                       |
-| ------------------- | ---------------- | ------------------------------------------------------------------ |
-| `drops.farming` 1.0 | Pear Drops       | Whether it's farming, which channel, and the drop's progress       |
-| `players` 1.0       | Stream Multiview | Its players by site: signed in or not, and which channels are open |
+| Capability          | Provided by      | What it says                                                                                                                                                               |
+| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `drops.farming` 1.0 | Pear Drops       | Whether it's farming: the channel, stream and drop, with pictures, the next reward and when it unlocks, enough for a widget. Also `show`, to bring Pear Drops to the front |
+| `players` 1.0       | Stream Multiview | Its players by site: signed in or not, and which channels are open                                                                                                         |
 
 To add one:
 
@@ -138,6 +160,12 @@ To change one, follow [the version rules](PROTOCOL.md#versions): additions are a
 
 Add it to `src/known-apps.js`, with its id, slug, summary, a 256×256 logo in `assets/apps/`, its download page and its data folder's name. Every app that updates Grapevine then shows it on its Connected apps page.
 
+## Renaming an app
+
+If your app's id changes, list the old one: `createLink({ app: { id: 'com.new.id', formerIds: ['com.old.id'], … } })`. Apps paired with it carry on without pairing again. Then add the new id to `src/known-apps.js`, with the old one in its `formerIds`.
+
+When another app was renamed, `link.currentId(oldId)` gives its new id, so you can move your own settings across (its Connect switch, say). [`PROTOCOL.md`](PROTOCOL.md#renaming-an-app) has the details.
+
 ## Developing
 
 ```sh

package/fixtures/drops.farming/1/invalid/image-not-https.json

@@ -0,0 +1,11 @@
+{
+  "event": "drops.farming.changed",
+  "params": {
+    "seq": 1,
+    "at": "2026-10-18T09:12:04Z",
+    "state": "farming",
+    "account": null,
+    "channel": { "platform": "kick", "slug": "pixelpear", "avatar": "pd-img://x.png" },
+    "drop": null
+  }
+}

package/fixtures/drops.farming/1/invalid/next-without-name.json

@@ -0,0 +1,11 @@
+{
+  "event": "drops.farming.changed",
+  "params": {
+    "seq": 1,
+    "at": "2026-10-18T09:12:04Z",
+    "state": "farming",
+    "account": null,
+    "channel": null,
+    "drop": { "campaign": "c", "category": "c", "progress": { "done": 1, "total": 2, "unit": "minutes" }, "next": { "required": 60 } }
+  }
+}

package/fixtures/drops.farming/1/valid/farming-plain.json

@@ -0,0 +1,12 @@
+{
+  "event": "drops.farming.changed",
+  "note": "Only the required fields: the rest are optional",
+  "params": {
+    "seq": 41,
+    "at": "2026-10-18T09:10:00Z",
+    "state": "farming",
+    "account": null,
+    "channel": { "platform": "kick", "slug": "pixelpear" },
+    "drop": { "campaign": "Neon Rush Launch Week", "category": "Neon Rush", "progress": { "done": 46, "total": 120, "unit": "minutes" } }
+  }
+}

package/fixtures/drops.farming/1/valid/farming.json

@@ -5,7 +5,22 @@
     "at": "2026-10-18T09:12:04.120Z",
     "state": "farming",
     "account": { "platform": "kick", "user": "pearfan" },
-    "channel": { "platform": "kick", "slug": "pixelpear", "name": "PixelPear" },
-    "drop": { "campaign": "Neon Rush Launch Week", "category": "Neon Rush", "progress": { "done": 48, "total": 120, "unit": "minutes" } }
+    "channel": { "platform": "kick", "slug": "pixelpear", "name": "PixelPear", "avatar": "https://files.kick.com/images/user/1/profile_image/pixelpear.webp" },
+    "stream": { "title": "Neon Rush ranked, chill vibes", "viewers": 1240 },
+    "drop": {
+      "campaign": "Neon Rush Launch Week",
+      "category": "Neon Rush",
+      "progress": { "done": 48, "total": 120, "unit": "minutes" },
+      "image": "https://files.kick.com/images/subcategories/1/banner/neon-rush.webp",
+      "endsAt": "2026-10-21T18:00:00Z",
+      "doneAt": "2026-10-18T10:24:00Z",
+      "rewards": { "claimed": 1, "total": 3 },
+      "next": {
+        "name": "Hype Rocket Emote",
+        "image": "https://files.kick.com/drops/reward/hype-rocket.png",
+        "required": 60,
+        "unlocksAt": "2026-10-18T09:24:00Z"
+      }
+    }
   }
 }

package/fixtures/drops.farming/1/valid/show-result.json

@@ -0,0 +1 @@
+{ "result": "drops.farming.show", "params": { "shown": true } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamorchard/grapevine",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Lets desktop apps on the same computer find each other and talk, privately: local sockets, JSON-RPC, pairing and versioned capabilities.",
   "license": "GPL-3.0-only",
   "author": "StreamOrchard",

package/schemas/common.json

@@ -1,7 +1,17 @@
 {
   "description": "Types every capability shares. Lists marked x-open may gain values: an app must accept a value it doesn't know.",
   "defs": {
-    "Timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601, in UTC" },
+    "Timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601, in UTC"
+    },
+    "Image": {
+      "type": "string",
+      "pattern": "^https://",
+      "maxLength": 2000,
+      "description": "A picture's https address, as the site gives it"
+    },
     "Platform": {
       "type": "string",
       "pattern": "^[a-z0-9-]{1,32}$",
@@ -12,9 +22,24 @@
       "type": "object",
       "required": ["platform", "slug"],
       "properties": {
-        "platform": { "$ref": "common:Platform" },
-        "slug": { "type": "string", "minLength": 1, "maxLength": 100, "description": "As in the channel's address" },
-        "name": { "type": "string", "maxLength": 200, "description": "As shown on the site" }
+        "platform": {
+          "$ref": "common:Platform"
+        },
+        "slug": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "As in the channel's address"
+        },
+        "name": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "As shown on the site"
+        },
+        "avatar": {
+          "$ref": "common:Image",
+          "description": "The channel's picture"
+        }
       }
     },
     "Account": {
@@ -22,19 +47,36 @@
       "required": ["platform", "user"],
       "description": "Who an app is signed in as: the username only, never a token or cookie",
       "properties": {
-        "platform": { "$ref": "common:Platform" },
-        "user": { "type": "string", "minLength": 1, "maxLength": 100 }
+        "platform": {
+          "$ref": "common:Platform"
+        },
+        "user": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        }
       }
     },
     "Progress": {
       "type": "object",
       "required": ["done", "total", "unit"],
       "properties": {
-        "done": { "type": "number", "minimum": 0 },
-        "total": { "type": "number", "minimum": 0 },
-        "unit": { "type": "string", "x-open": ["minutes"] }
+        "done": {
+          "type": "number",
+          "minimum": 0
+        },
+        "total": {
+          "type": "number",
+          "minimum": 0
+        },
+        "unit": {
+          "type": "string",
+          "x-open": ["minutes"]
+        }
       }
     },
-    "Empty": { "type": "object" }
+    "Empty": {
+      "type": "object"
+    }
   }
 }

package/schemas/drops.farming/1.json

@@ -2,20 +2,50 @@
   "capability": "drops.farming",
   "major": 1,
   "minor": 0,
-  "description": "What a drops app is farming. Provided by Pear Drops.",
+  "description": "What a drops app is farming, with enough to show it (a top-bar widget, say). Provided by Pear Drops.",
   "events": {
-    "drops.farming.changed": { "$ref": "#State" }
+    "drops.farming.changed": {
+      "$ref": "#State"
+    }
   },
   "methods": {
-    "drops.farming.get": { "params": { "$ref": "common:Empty" }, "result": { "$ref": "#State" } }
+    "drops.farming.get": {
+      "params": {
+        "$ref": "common:Empty"
+      },
+      "result": {
+        "$ref": "#State"
+      }
+    },
+    "drops.farming.show": {
+      "params": {
+        "$ref": "common:Empty"
+      },
+      "result": {
+        "type": "object",
+        "required": ["shown"],
+        "properties": {
+          "shown": {
+            "type": "boolean",
+            "description": "Whether its window came to the front"
+          }
+        }
+      }
+    }
   },
   "defs": {
     "State": {
       "type": "object",
       "required": ["seq", "at", "state", "account", "channel", "drop"],
       "properties": {
-        "seq": { "type": "integer", "minimum": 0, "description": "Counts up with each change; 0 for a reply to drops.farming.get" },
-        "at": { "$ref": "common:Timestamp" },
+        "seq": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Counts up with each change; 0 for a reply to drops.farming.get"
+        },
+        "at": {
+          "$ref": "common:Timestamp"
+        },
         "state": {
           "type": "string",
           "minLength": 1,
@@ -23,21 +53,141 @@
           "x-open": ["farming", "waiting", "paused", "done", "signed-out"],
           "description": "farming: its player is watching a stream for drop credit. Any other value, known or not, means it isn't."
         },
-        "account": { "anyOf": [{ "$ref": "common:Account" }, { "type": "null" }] },
-        "channel": { "anyOf": [{ "$ref": "common:Channel" }, { "type": "null" }], "description": "The stream being watched, while farming" },
+        "account": {
+          "anyOf": [
+            {
+              "$ref": "common:Account"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "channel": {
+          "anyOf": [
+            {
+              "$ref": "common:Channel"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The stream being watched, while farming"
+        },
         "drop": {
           "anyOf": [
             {
               "type": "object",
               "required": ["campaign", "category", "progress"],
               "properties": {
-                "campaign": { "type": "string", "maxLength": 200 },
-                "category": { "type": "string", "maxLength": 200 },
-                "progress": { "$ref": "common:Progress" }
+                "campaign": {
+                  "type": "string",
+                  "maxLength": 200
+                },
+                "category": {
+                  "type": "string",
+                  "maxLength": 200
+                },
+                "progress": {
+                  "$ref": "common:Progress"
+                },
+                "image": {
+                  "$ref": "common:Image",
+                  "description": "The category's picture"
+                },
+                "endsAt": {
+                  "$ref": "common:Timestamp",
+                  "description": "When the drop ends"
+                },
+                "doneAt": {
+                  "anyOf": [
+                    {
+                      "$ref": "common:Timestamp"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "When every reward should be earned, at the current rate"
+                },
+                "rewards": {
+                  "type": "object",
+                  "required": ["claimed", "total"],
+                  "properties": {
+                    "claimed": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "total": {
+                      "type": "integer",
+                      "minimum": 0
+                    }
+                  }
+                },
+                "next": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "required": ["name", "required"],
+                      "properties": {
+                        "name": {
+                          "type": "string",
+                          "maxLength": 200
+                        },
+                        "image": {
+                          "$ref": "common:Image"
+                        },
+                        "required": {
+                          "type": "number",
+                          "minimum": 0,
+                          "description": "Minutes of watching it unlocks at"
+                        },
+                        "unlocksAt": {
+                          "anyOf": [
+                            {
+                              "$ref": "common:Timestamp"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ],
+                          "description": "When it should unlock, at the current rate"
+                        }
+                      }
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The reward being worked towards"
+                }
               }
             },
-            { "type": "null" }
+            {
+              "type": "null"
+            }
           ]
+        },
+        "stream": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "title": {
+                  "type": "string",
+                  "maxLength": 300
+                },
+                "viewers": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The stream being watched, while farming: its title and viewers"
         }
       }
     }

package/src/connection.js

@@ -22,7 +22,11 @@ const TIMING = Object.freeze({
  * @property {object} self this app's description (the hello's "app")
  * @property {{provides: Record<string, string[]>, uses: Record<string, string[]>}} mine
  * @property {{get(id: string): {key: string, pairedAt?: string} | null, set(id: string, key: string): void, delete(id: string): void}} keys
- * @property {(id: string) => boolean} allowed whether this app's switch for that app is on
+ * @property {(ids: string[]) => boolean} allowed whether this app's switch for that app (under any of its ids) is on
+ * @property {(id: string) => string[]} idsOf a known app's id and former ids
+ * @property {(app: {id: string, slug: string, formerIds?: string[]}) => {id: string, ids: string[]}} resolve
+ *   the id this app knows another app by (its known-apps entry, matched by any id), and every id it has had
+ * @property {(ids: string[]) => {key: string, pairedAt?: string} | null} findKey the pairing key, filed under any of those ids
  * @property {import('./schema').Schemas} schemas
  * @property {(conn: Connection, method: string, params: any) => Promise<any>} call runs a capability method
  * @property {(conn: Connection, events: string[]) => string[]} subscribe
@@ -45,7 +49,9 @@ class Connection extends EventEmitter {
     this.expectedId = expectedId ?? null;
     this.state = 'hello'; // hello -> auth -> ready -> closed (the connecting app: hello -> authing -> ready)
     this.peer = null; // the other app's description, from its hello
-    this.peerId = null;
+    this.peerId = null; // the id this app knows the other one by
+    /** @type {string[]} */
+    this.peerIds = []; // and every id it has had
     this.agreed = { incoming: new Map(), outgoing: new Map(), missing: [] };
     this.protocol = null;
     this.subscribed = new Set(); // events the other app subscribed to
@@ -85,7 +91,9 @@ class Connection extends EventEmitter {
   /** Says hello, checks the reply's proof, proves itself, and is ready. */
   async start() {
     const { self, mine, keys } = this.host;
-    const stored = keys.get(this.expectedId);
+    // The key may be filed under a former id of that app: one it had before a rename.
+    const expectedIds = this.host.idsOf(this.expectedId);
+    const stored = this.host.findKey(expectedIds);
     const clientNonce = hs.nonce();
     let res;
     try {
@@ -99,7 +107,8 @@ class Connection extends EventEmitter {
     }
     const problems = hs.checkApp(res?.app);
     if (problems.length) return this.close(`Its hello reply isn't valid: ${problems.join('; ')}`);
-    if (this.expectedId && res.app.id !== this.expectedId) return this.close(`Expected ${this.expectedId}, but ${res.app.id} answered`);
+    const theirIds = [res.app.id, ...(res.app.formerIds ?? [])];
+    if (!theirIds.some((i) => expectedIds.includes(i))) return this.close(`Expected ${this.expectedId}, but ${res.app.id} answered`);
     if (hs.agreeProtocol(hs.PROTOCOL, { min: res.protocol, max: res.protocol }) === null)
       return this.close(`It chose protocol ${res.protocol}, which this app doesn't speak`);
     const key = stored?.key ?? res.auth?.key;
@@ -109,7 +118,8 @@ class Connection extends EventEmitter {
       return this.close("Its proof was wrong: the pairing doesn't match");
     }
     this.peer = res.app;
-    this.peerId = res.app.id;
+    this.peerId = this.expectedId; // the id this app knows it by, whatever it calls itself now
+    this.peerIds = [...new Set([...expectedIds, ...theirIds])];
     this.protocol = res.protocol;
     this.agreed = hs.agree(mine, res.capabilities);
     this.state = 'authing';
@@ -141,10 +151,10 @@ class Connection extends EventEmitter {
       this.emit('status', { status: 'incompatible', peer: params.app, theirProtocol: params.protocol });
       return this.reject(id, new GrapevineError(CODES.UNSUPPORTED, 'No protocol version in common', { protocol: hs.PROTOCOL }));
     }
-    const peerId = params.app.id;
-    if (!this.host.allowed(peerId))
+    const { id: peerId, ids } = this.host.resolve(params.app);
+    if (!this.host.allowed(ids))
       return this.reject(id, new GrapevineError(CODES.SWITCHED_OFF, `${this.host.self.name} isn't set to connect with ${params.app.name}`));
-    const stored = this.host.keys.get(peerId);
+    const stored = this.host.findKey(ids);
     let key;
     if (params.auth.pair) {
       // An app asking to pair while this one still has a key: only once you press Pair again here.
@@ -164,6 +174,7 @@ class Connection extends EventEmitter {
     this.pending = { key, serverNonce, pairing: !!params.auth.pair };
     this.peer = params.app;
     this.peerId = peerId;
+    this.peerIds = ids;
     this.protocol = protocol;
     this.agreed = hs.agree(this.host.mine, params.capabilities);
     this.state = 'auth';
@@ -265,7 +276,7 @@ class Connection extends EventEmitter {
       return this.host.afterSubscribe?.(this);
     }
     if (method === 'link.unpair') {
-      this.host.keys.delete(this.peerId);
+      for (const i of this.peerIds) this.host.keys.delete(i);
       this.rpc.reply(id, {});
       this.emit('unpaired');
       return this.close('Disconnected in the other app');

package/src/handshake.js

@@ -116,6 +116,12 @@ function checkApp(app) {
   if (app.icon !== undefined && (typeof app.icon !== 'string' || !app.icon.startsWith('data:image/png;base64,') || app.icon.length > MAX_ICON))
     p.push('app.icon: a PNG data URL, up to 256 KB');
   for (const k of ['homepage', 'download']) if (app[k] !== undefined && !isHttps(app[k])) p.push(`app.${k}: an https address`);
+  if (
+    app.formerIds !== undefined &&
+    (!Array.isArray(app.formerIds) || app.formerIds.length > 10 || !app.formerIds.every((i) => typeof i === 'string' && ID_RE.test(i) && i !== app.id))
+  ) {
+    p.push('app.formerIds: up to 10 ids it had before, not its own');
+  }
   return p;
 }
 

package/src/index.js

@@ -20,7 +20,7 @@ const POLL_MS = 5000;
 
 /**
  * @typedef {object} LinkOptions
- * @property {{id: string, slug: string, name: string, version: string, summary?: string, icon?: string, homepage?: string, download?: string}} app
+ * @property {{id: string, slug: string, name: string, version: string, formerIds?: string[], summary?: string, icon?: string, homepage?: string, download?: string}} app
  *   This app, as other apps will see it. `icon` may be a PNG data URL or a file path.
  * @property {Record<string, string | string[]>} [provides] capabilities this app provides, e.g. { 'drops.farming': '1.0' }
  * @property {Record<string, string | string[]>} [uses] capabilities it uses, e.g. { players: '1.0' }
@@ -40,7 +40,8 @@ class Link extends EventEmitter {
   constructor(opts) {
     super();
     const icon = opts.app.icon && !opts.app.icon.startsWith('data:') ? iconDataUrl(opts.app.icon) : opts.app.icon;
-    this.self = { ...opts.app, ...(icon ? { icon } : {}) };
+    // formerIds: ids this app had before a rename, so apps paired with it then still know it. Sent every time, [] until then.
+    this.self = { ...opts.app, formerIds: opts.app.formerIds ?? [], ...(icon ? { icon } : {}) };
     const problems = hs.checkApp(this.self);
     if (problems.length) throw new Error(`createLink: ${problems.join('; ')}`);
     this.mine = { provides: hs.normalizeList(opts.provides), uses: hs.normalizeList(opts.uses) };
@@ -49,7 +50,8 @@ class Link extends EventEmitter {
     this.appDataDir = opts.appDataDir ?? null;
     this.place = opts.place ?? {};
     this.schemas = Schemas.load(opts.schemaDirs);
-    this.knownApps = (opts.knownApps ?? KNOWN_APPS).filter((a) => a.id !== this.self.id);
+    const mine = new Set([this.self.id, ...this.self.formerIds]);
+    this.knownApps = (opts.knownApps ?? KNOWN_APPS).filter((a) => !mine.has(a.id) && !(a.formerIds ?? []).some((i) => mine.has(i)));
     this.timing = { ...TIMING, pollMs: POLL_MS, backoffMs: BACKOFF_MS, ...opts.timing };
     this.strict = opts.strict ?? process.env.NODE_ENV === 'test';
     this.logFn = opts.log ?? (() => {});
@@ -138,9 +140,9 @@ class Link extends EventEmitter {
 
   /** Call after a Connected apps switch changes: closes connections switched off, looks for ones switched on. */
   refresh() {
-    for (const [id, c] of this.conns) if (!this.allowed(id)) c.bye(`Switched off in ${this.self.name}`);
-    for (const c of this.opening) if (c.peerId && !this.allowed(c.peerId)) c.close('Switched off');
-    for (const a of this.knownApps) if (this.allowed(a.id)) this.retry.delete(a.id);
+    for (const [, c] of this.conns) if (!this.allowedAny(c.peerIds)) c.bye(`Switched off in ${this.self.name}`);
+    for (const c of this.opening) if (c.peerIds.length && !this.allowedAny(c.peerIds)) c.close('Switched off');
+    for (const a of this.knownApps) if (this.allowedAny(this.idsOf(a.id))) this.retry.delete(a.id);
     this.poll();
     this.changed();
   }
@@ -153,6 +155,43 @@ class Link extends EventEmitter {
     }
   }
 
+  /** Whether the switch is on under any of an app's ids (it may still be saved under a former one). */
+  allowedAny(ids) {
+    return ids.some((id) => this.allowed(id));
+  }
+
+  /** A known app's id and its former ids; just the id for an app that isn't known. */
+  idsOf(id) {
+    const app = this.knownApps.find((a) => a.id === id || (a.formerIds ?? []).includes(id));
+    return app ? [app.id, ...(app.formerIds ?? [])] : [id];
+  }
+
+  /** The id this app knows another one by (its known-apps entry, matched on any id either side lists), and every id it has had. */
+  resolve(app) {
+    const theirs = [app.id, ...(app.formerIds ?? [])];
+    const known = this.knownApps.find((a) => [a.id, ...(a.formerIds ?? [])].some((i) => theirs.includes(i)));
+    const id = known?.id ?? app.id;
+    return { id, ids: [...new Set([...(known ? this.idsOf(known.id) : []), ...theirs])] };
+  }
+
+  /** The pairing key, under whichever of these ids it was filed. */
+  findKey(ids) {
+    for (const id of ids) {
+      const k = this.keys.get(id);
+      if (k) return k;
+    }
+    return null;
+  }
+
+  /**
+   * The id to use for an app: its current id, given any it has had. For moving an app's own
+   * settings across after the other app was renamed: settings[link.currentId(old)] = settings[old].
+   */
+  currentId(id) {
+    for (const c of this.conns.values()) if (c.peerIds.includes(id)) return c.peerId;
+    return this.idsOf(id)[0];
+  }
+
   // ------------------------------------------------------------------ finding apps
 
   pollSoon() {
@@ -162,14 +201,15 @@ class Link extends EventEmitter {
   }
 
   /**
-   * Connects to apps that are running and switched on. Of two apps, the one whose id sorts first
-   * connects and the other waits, so they don't both connect at once.
+   * Connects to apps that are running and switched on. Of two apps, the one whose slug sorts first
+   * connects and the other waits, so they don't both connect at once. (Slugs, not ids: an app's id
+   * may change, its socket's name doesn't.)
    */
   poll() {
     if (!this.running) return;
     const slugs = new Set(paths.listSlugs(this.place));
     for (const app of this.knownApps) {
-      if (!slugs.has(app.slug) || !this.allowed(app.id) || this.conns.has(app.id) || this.self.id > app.id) continue;
+      if (!slugs.has(app.slug) || !this.allowedAny(this.idsOf(app.id)) || this.conns.has(app.id) || this.self.slug > app.slug) continue;
       if ([...this.opening].some((c) => (c.expectedId ?? c.peerId) === app.id)) continue;
       const r = this.retry.get(app.id);
       if (r && Date.now() < r.at) continue;
@@ -191,7 +231,7 @@ class Link extends EventEmitter {
   track(conn) {
     this.opening.add(conn);
     conn.on('status', (s) => {
-      const id = conn.expectedId ?? s.peer?.id ?? conn.peerId;
+      const id = conn.expectedId ?? (s.peer ? this.resolve(s.peer).id : conn.peerId);
       if (!id) return;
       this.why.set(id, { ...s, peer: undefined, theirApp: s.peer });
       this.changed();
@@ -210,8 +250,8 @@ class Link extends EventEmitter {
     const id = conn.peerId;
     const other = this.conns.get(id);
     if (other) {
-      // Both connected at once: keep the one made by the app whose id sorts first.
-      const firstOf = (c) => (c.initiator ? this.self.id : c.peerId);
+      // Both connected at once: keep the one made by the app whose slug sorts first.
+      const firstOf = (c) => (c.initiator ? this.self.slug : c.peer.slug);
       const [keep, drop] = firstOf(conn) <= firstOf(other) ? [conn, other] : [other, conn];
       this.conns.set(id, keep);
       drop.bye('duplicate');
@@ -247,7 +287,10 @@ class Link extends EventEmitter {
       self: this.self,
       mine: this.mine,
       keys: this.keys,
-      allowed: (id) => this.allowed(id),
+      allowed: (ids) => this.allowedAny(ids),
+      idsOf: (id) => this.idsOf(id),
+      resolve: (app) => this.resolve(app),
+      findKey: (ids) => this.findKey(ids),
       schemas: this.schemas,
       timing: this.timing,
       log: (level, text) => this.log(level, text),
@@ -332,7 +375,7 @@ class Link extends EventEmitter {
 
   /** Asks a connected app something. Rejects with a GrapevineError (CLOSED if it isn't connected). */
   async request(appId, method, params = {}, opts) {
-    const conn = this.conns.get(appId);
+    const conn = this.conns.get(this.currentId(appId));
     if (!conn) throw new GrapevineError(CODES.CLOSED, `Not connected to ${appId}`);
     const cap = this.schemas.capabilityOf(method);
     const agreed = cap && conn.agreed.incoming.get(cap);
@@ -347,27 +390,29 @@ class Link extends EventEmitter {
 
   /** Disconnect on a card: tells the other app to forget the pairing, and forgets it here. Switch this app's own setting off too. */
   async disconnect(appId) {
-    const conn = this.conns.get(appId);
+    const id = this.currentId(appId);
+    const conn = this.conns.get(id);
     if (conn) {
       await conn.rpc.request('link.unpair', {}, { timeout: 2000 }).catch(() => {});
       conn.close('Disconnected');
     }
-    this.keys.delete(appId);
-    this.why.delete(appId);
+    for (const i of new Set([...this.idsOf(id), ...(conn?.peerIds ?? [])])) this.keys.delete(i);
+    this.why.delete(id);
     this.changed();
   }
 
   /** "Pair again" on a card: forgets this app's old key, so the next connection pairs afresh. */
   pairAgain(appId) {
-    this.keys.delete(appId);
-    this.why.delete(appId);
-    this.retry.delete(appId);
+    const id = this.currentId(appId);
+    for (const i of this.idsOf(id)) this.keys.delete(i);
+    this.why.delete(id);
+    this.retry.delete(id);
     this.poll();
     this.changed();
   }
 
   isConnected(appId) {
-    return this.conns.has(appId);
+    return this.conns.has(this.currentId(appId));
   }
 
   /**
@@ -378,8 +423,8 @@ class Link extends EventEmitter {
     return this.knownApps.map((app) => {
       const conn = this.conns.get(app.id);
       const why = this.why.get(app.id);
-      const enabled = this.allowed(app.id);
-      const paired = this.keys.get(app.id);
+      const enabled = this.allowedAny(this.idsOf(app.id));
+      const paired = this.findKey(this.idsOf(app.id));
       let status = !enabled ? 'off' : conn ? 'connected' : (why?.status ?? 'waiting');
       if (status === 'connected' && !conn) status = 'waiting';
       let report = null;
@@ -387,6 +432,7 @@ class Link extends EventEmitter {
       else if (status === 'incompatible' && why?.theirProtocol) report = incompatible(this.self, why.theirApp ?? app, hs.PROTOCOL, why.theirProtocol);
       return {
         id: app.id,
+        formerIds: app.formerIds ?? [],
         name: app.name,
         summary: app.summary,
         icon: app.icon,

package/src/known-apps.js

@@ -11,6 +11,7 @@ const ICONS = path.join(__dirname, '..', 'assets', 'apps');
 /**
  * @typedef {object} KnownApp
  * @property {string} id the app's install id (the hello's app.id)
+ * @property {string[]} formerIds ids it had before a rename: an app paired under one of them is still known
  * @property {string} slug its socket name
  * @property {string} name
  * @property {string} summary one sentence, for its card
@@ -25,6 +26,7 @@ const ICONS = path.join(__dirname, '..', 'assets', 'apps');
 const KNOWN_APPS = [
   {
     id: 'com.streamorchard.peardrops',
+    formerIds: [],
     slug: 'pear-drops',
     name: 'Pear Drops',
     summary: "Collects your Kick emote and badge drops for you, watching with Kick's own player.",
@@ -36,6 +38,7 @@ const KNOWN_APPS = [
   },
   {
     id: 'com.glowingpear.streammultiview',
+    formerIds: [],
     slug: 'stream-multiview',
     name: 'Stream Multiview',
     summary: 'Watch Kick, Twitch and YouTube streams and chats side by side, with custom layouts, live alerts and color themes.',

package/stand-in-peer.js

@@ -26,13 +26,27 @@ const { createLink, KNOWN_APPS, memoryKeyStore } = require('./src');
  * @param {(appId: string) => boolean} [o.allowed] its switch (default: on for every app)
  * @param {object} [o.timing]
  * @param {import('./src/keys').KeyStore} [o.keys]
+ * @param {string} [o.id] a new id to answer with in place of the known app's (to test a rename)
+ * @param {string[]} [o.formerIds]
  */
-async function standInPeer({ as, dir, version = '99.0.0', provides = {}, uses = {}, allowed = () => true, timing, keys = memoryKeyStore() }) {
+async function standInPeer({
+  as,
+  dir,
+  version = '99.0.0',
+  provides = {},
+  uses = {},
+  allowed = () => true,
+  timing,
+  keys = memoryKeyStore(),
+  id,
+  formerIds = [],
+}) {
   const known = KNOWN_APPS.find((a) => a.id === as);
   if (!known) throw new Error(`stand-in-peer: ${as} isn't a known app`);
   const link = createLink({
     app: {
-      id: known.id,
+      id: id ?? known.id,
+      formerIds,
       slug: known.slug,
       name: `${known.name} (stand-in)`,
       version,

package/types/capabilities.d.ts

@@ -3,6 +3,9 @@
 /** ISO 8601, in UTC */
 export type Timestamp = string;
 
+/** A picture's https address, as the site gives it */
+export type Image = string;
+
 /** A streaming site */
 export type Platform = "kick" | "twitch" | "youtube" | (string & {});
 
@@ -12,6 +15,8 @@ export type Channel = {
   slug: string;
   /** As shown on the site */
   name?: string;
+  /** The channel's picture */
+  avatar?: Image;
 };
 
 /** Who an app is signed in as: the username only, never a token or cookie */
@@ -28,7 +33,7 @@ export type Progress = {
 
 export type Empty = Record<string, unknown>;
 
-// drops.farming 1.0: What a drops app is farming. Provided by Pear Drops.
+// drops.farming 1.0: What a drops app is farming, with enough to show it (a top-bar widget, say). Provided by Pear Drops.
 export type DropsFarmingV1State = {
   /** Counts up with each change; 0 for a reply to drops.farming.get */
   seq: number;
@@ -42,6 +47,30 @@ export type DropsFarmingV1State = {
     campaign: string;
     category: string;
     progress: Progress;
+    /** The category's picture */
+    image?: Image;
+    /** When the drop ends */
+    endsAt?: Timestamp;
+    /** When every reward should be earned, at the current rate */
+    doneAt?: Timestamp | null;
+    rewards?: {
+      claimed: number;
+      total: number;
+    };
+    /** The reward being worked towards */
+    next?: {
+      name: string;
+      image?: Image;
+      /** Minutes of watching it unlocks at */
+      required: number;
+      /** When it should unlock, at the current rate */
+      unlocksAt?: Timestamp | null;
+    } | null;
+  } | null;
+  /** The stream being watched, while farming: its title and viewers */
+  stream?: {
+    title?: string;
+    viewers?: number;
   } | null;
 };
 
@@ -73,5 +102,9 @@ export interface Events {
 /** Every method, by name: its params and result. */
 export interface Methods {
   "drops.farming.get": { params: Empty; result: DropsFarmingV1State };
+  "drops.farming.show": { params: Empty; result: {
+      /** Whether its window came to the front */
+      shown: boolean;
+    } };
   "players.get": { params: Empty; result: PlayersV1State };
 }

package/types/index.d.ts

@@ -13,6 +13,8 @@ export type EventData<E extends EventName> = Omit<Events[E], 'seq' | 'at'>;
 export interface AppInfo {
   /** The app's install id, like com.example.app */
   id: string;
+  /** Ids it had before a rename (up to 10), so apps paired with it then still know it. Sent as [] until then. */
+  formerIds?: string[];
   /** Its socket name: a-z, 0-9 and dashes */
   slug: string;
   name: string;
@@ -51,6 +53,8 @@ export interface Timing {
 
 export interface KnownApp {
   id: string;
+  /** Ids it had before a rename */
+  formerIds: string[];
   slug: string;
   name: string;
   summary: string;
@@ -94,7 +98,9 @@ export interface Report {
 }
 
 export interface Peer {
+  /** The id this app knows it by */
   id: string;
+  formerIds: string[];
   name: string;
   summary: string;
   /** Path of its bundled logo */
@@ -145,6 +151,8 @@ export declare class Link extends EventEmitter {
   /** Pair again on a card: forgets this app's old key. */
   pairAgain(appId: string): void;
   isConnected(appId: string): boolean;
+  /** Its current id, given any id it has had: for moving your own settings across after another app is renamed. */
+  currentId(appId: string): string;
   /** Every known app, for the Connected apps page. */
   peers(): Peer[];