fix: add intents stuff

contributing.md

@@ -36,7 +36,7 @@ To submit a translation, please follow these steps:
 5. If you want to submit a pull request with the translated file:
     1. Duplicate the `en_US.json` file in the folder [`assets/translations/`](./assets/translations/) by keeping the format `languageCode_localeCode.json`
     2. Edit it to your translated version and keep the left side of the colon unchanged
-    3. Create the mapping in `assets/locales.json` by copying the english one and editing it (please make sure it's alphabetically ordered)
+    3. Create the mapping in `assets/locales.json` by copying the English one and editing it (please make sure it's alphabetically ordered)
     4. Add your name to the respective `authors` property in [`assets/locales.json`](./assets/locales.json)
     5. Test your changes by following [this section](#setting-up-the-project-for-local-development), then submit your pull request
 6. Alternatively send it to me directly, [see my homepage](https://sv443.net/) for contact info  
@@ -303,17 +303,20 @@ The usage and example blocks on each are written in TypeScript but can be used i
 > The function will either throw an error if the plugin object is invalid or return a registration result object.  
 > Its type can be found by searching for `type PluginRegisterResult` in the file [`src/types.ts`](./src/types.ts)
 > 
-> <details><summary><b>Example <i>(click to expand)</i></b></summary>
+> <details><summary><b>Complete example <i>(click to expand)</i></b></summary>
 > 
 > ```ts
+> // all properties are optional unless stated otherwise
+> // search for "type PluginDef" in "src/types.ts" to see the whole type
 > const pluginDef = {
 >   plugin: {
->     name: "My cool plugin",
->     namespace: "https://github.com/MyUsername",
->     version: [1, 0, 0],
->     description: {
->       en_US: "This is a plugin that does cool stuff",
->       de_DE: "Dies ist ein Plugin, das coole Sachen macht",
+>     name: "My cool plugin",                           // required
+>     namespace: "https://github.com/MyUsername",       // required
+>     version: [4, 2, 0],                               // required
+>     description: {                                    // required
+>       en_US: "This plugin does cool stuff",           // required
+>       de_DE: "Dieses Plugin macht coole Sachen",
+>       // see all supported locale codes in "assets/locales.json"
 >     },
 >     iconUrl: "https://picsum.photos/128/128",
 >     homepage: {
@@ -322,17 +325,31 @@ The usage and example blocks on each are written in TypeScript but can be used i
 >       openuserjs: "...",
 >     },
 >   },
+>   // the intents (permissions) the plugin needs to be granted
+>   // search for "enum PluginIntent" in "src/types.ts" to see all available intent values
+>   intents: [ 2, 16 ],
 >   contributors: [
 >     {
->       name: "MyUsername",
+>       name: "MyUsername", // required
 >       homepage: "https://github.com/MyUsername",
->       email: "[email protected]",
+>       email: "[email protected]",
+>     },
+>     {
+>       name: "SomeOtherGuy", // required
+>       homepage: "https://github.com/SomeOtherGuy",
+>       email: "[email protected]",
 >     },
 >   ],
 > };
 > 
-> unsafeWindow.addEventListener("bytm:ready", () => {
->   unsafeWindow.BYTM.registerPlugin(pluginDef);
+> unsafeWindow.addEventListener("bytm:initPlugins", () => {
+>   // register the plugin
+>   const { events } = unsafeWindow.BYTM.registerPlugin(pluginDef);
+>   // listen for the pluginRegistered event
+>   events.on("pluginRegistered", (info) => {
+>     console.log(`${info.name} (version ${info.version.join(".")}) is registered`);
+>   });
+>   // for other events search for "type PluginEventMap" in "src/types.ts"
 > });
 > ```
 > </details>

src/types.ts

@@ -50,21 +50,53 @@ export type LyricsCacheEntry = {
   added: number;
 };
 
+//#MARKER global
+
+// shim for the BYTM interface properties
+export type BytmObject =
+  {
+    [key: string]: unknown;
+    locale: TrLocale;
+    logLevel: LogLevel;
+  }
+  // information from the userscript header
+  & typeof scriptInfo
+  // certain variables from `src/constants.ts`
+  & Pick<typeof consts, "mode" | "branch" | "host" | "buildNumber" | "compressionFormat">
+  // global functions exposed through the interface in `src/interface.ts`
+  & InterfaceFunctions
+  // others
+  & {
+    // the entire UserUtils library
+    UserUtils: typeof import("@sv443-network/userutils");
+  };
+
+declare global {
+  interface Window {
+    // to see the expanded type, install the VS Code extension "MylesMurphy.prettify-ts" and hover over the property below
+    // alternatively navigate with ctrl+click to find the types
+    BYTM: BytmObject;
+  }
+}
+
 //#MARKER plugins
 
-// /** Intents (permissions) BYTM has to grant to the plugin for it to work */
-// export enum PluginIntent {
-//   /** Plugin has access to hidden config values */
-//   HiddenConfigValues = 1,
-//   /** Plugin can write to the feature configuration */
-//   WriteFeatureConfig = 2,
-//   /** Plugin can write to the lyrics cache */
-//   WriteLyricsCache = 4,
-//   /** Plugin can add new translations and overwrite existing ones */
-//   WriteTranslations = 8,
-//   /** Plugin can create modal dialogs */
-//   CreateModalDialogs = 16,
-// }
+/**
+ * Intents (permissions) BYTM has to grant your plugin for it to be able to access certain features.  
+ * TODO: this feature is unfinished, but you should still specify the intents your plugin needs.
+ */
+export enum PluginIntent {
+  /** Plugin has access to hidden config values */
+  HiddenConfigValues = 1,
+  /** Plugin can write to the feature configuration */
+  WriteFeatureConfig = 2,
+  /** Plugin can write to the lyrics cache */
+  WriteLyricsCache = 4,
+  /** Plugin can add new translations and overwrite existing ones */
+  WriteTranslations = 8,
+  /** Plugin can create modal dialogs */
+  CreateModalDialogs = 16,
+}
 
 /** Result of a plugin registration */
 export type PluginRegisterResult = {
@@ -113,8 +145,8 @@ export type PluginDef = {
       openuserjs?: string;
     };
   };
-  // /** TODO(v2.3 / v3): Intents (permissions) BYTM has to grant the plugin for it to work */
-  // intents?: Array<PluginIntent>;
+  /** Intents (permissions) BYTM has to grant the plugin for it to work */
+  intents?: Array<PluginIntent>;
   /** Info about the plugin contributors */
   contributors?: Array<{
     /** Name of this contributor */
@@ -126,10 +158,9 @@ export type PluginDef = {
   }>;
 };
 
-/** All events that are dispatched to plugins individually */
+/** All events that are dispatched to plugins individually, including everything in {@linkcode SiteEventsMap} - these don't have a prefix since they can't conflict with other events */
 export type PluginEventMap =
   & {
-
     /** Called when the plugin is registered on BYTM's side */
     pluginRegistered: (info: PluginInfo) => void;
   }
@@ -172,33 +203,6 @@ export type InterfaceFunctions = {
   saveFeatures: typeof saveFeatures;
 };
 
-// shim for the BYTM interface properties
-export type BytmObject =
-  {
-    [key: string]: unknown;
-    locale: TrLocale;
-    logLevel: LogLevel;
-  }
-  // information from the userscript header
-  & typeof scriptInfo
-  // certain variables from `src/constants.ts`
-  & Pick<typeof consts, "mode" | "branch" | "host" | "buildNumber" | "compressionFormat">
-  // global functions exposed through the interface in `src/interface.ts`
-  & InterfaceFunctions
-  // others
-  & {
-    // the entire UserUtils library
-    UserUtils: typeof import("@sv443-network/userutils");
-  };
-
-declare global {
-  interface Window {
-    // to see the expanded type, install the VS Code extension "MylesMurphy.prettify-ts"
-    // and hover over the property just below:
-    BYTM: BytmObject;
-  }
-}
-
 //#MARKER features
 
 export type FeatureKey = keyof FeatureConfig;