Extract RPC-related types into a new type module

Extract RPC typing into its own module to avoid dependencies between
the store and the RPC implementation. Clarify a few points in other
types.

src/sidebar/cross-origin-rpc.js

@@ -3,15 +3,7 @@ import warnOnce from '../shared/warn-once';
 import { normalizeGroupIds } from './helpers/groups';
 
 /**
- * @typedef FocusUserInfo
- * @prop {string} [userid]
- * @prop {string} [username]
- * @prop {string} [displayName] - User's display name
- * @prop {string[]} [groups] - A list of group IDs that correspond to the
- *   focused user's list of groups. This is assumed to represent a subset
- *   of the `groups` currently loaded in the store. Each entry in this array
- *   may be either an `id` (a.k.a. `pubid`) OR a `groupid`. These should be
- *   normalized to `id`s (`pubid`s) before use with the store.
+ * @typedef {import('../types/rpc').FocusUserInfo} FocusUserInfo
  */
 
 // Array to keep track of pre-start requests

src/sidebar/store/modules/filters.js

@@ -23,7 +23,7 @@ import { createStoreModule } from '../create-store';
 
 /**
  *
- * @typedef { import('../../cross-origin-rpc').FocusUserInfo } FocusUserInfo
+ * @typedef {import('../../../types/rpc').FocusUserInfo} FocusUserInfo
  */
 
 /**

src/types/api.js

@@ -158,16 +158,20 @@
  * @prop {string} name
  * @prop {boolean} canLeave
  *
+ */
+
+/**
  * @typedef {NonNullable<Group["id"]|Group["groupid"]>} GroupIdentifier
- * Historically, Groups have been identified by their `id` (a.k.a. `pubid`)
- * property, which is a unique identifier per authority.
  *
- * Third-party groups, especially LMS groups, use `groupid` as an identifier
- * because it is unique across all authorities.
+ * All Groups have an `id`, which is a server-assigned identifier. This is the
+ * primary field used to identify a Group.
+ *
+ * In some cases, specifically LMS, it is necessary for an outside service to
+ * be able to specify its own identifier. This gets stored in the `groupid`
+ * field of a Group. Only some Groups have a `groupid`.
  *
- * Application logic operates on `id`s, but may receive `groupid`s as
- * identifiers from outside services. All groups are guaranteed to have an `id`,
- * but not all groups have a `groupid`.
+ * Application logic operates on `id`s, but we may receive `groupid`s in some
+ * cases from outside sevices, e.g. the `changeFocusModeUser` RPC method.
  */
 
 /**

src/types/rpc.js

+/**
+ * Type definitions for methods available to embedding frames that contain
+ * a host frame. This is specifically used by the LMS integration application.
+ */
+
+/** @typedef {import('./api').GroupIdentifier} GroupIdentifier */
+
+/**
+ * Data about a user to focus on in the sidebar. The intent is that the
+ * sidebar will filter annotations such that only those authored by this
+ * user are shown. If `groups` are provided, the sidebar will filter the set
+ * of shown groups to that set.
+ *
+ * @typedef FocusUserInfo
+ * @prop {string} [userid]
+ * @prop {string} [username]
+ * @prop {string} [displayName] - User's display name
+ * @prop {GroupIdentifier[]} [groups] - A list of group identifiers that
+ *   correspond to a set of groups specific to this focused user. This is
+ *   assumed to be a subset of the groups currently loaded in the store. These
+ *   identifiers, which can be either `id`s or `groupid`s, should be normalized
+ *   to `id`s before use with the store.
+ */
+
+// Make TypeScript treat this file as a module.
+export const unused = {};