Add auth header in plugins guide

[github/Chocobozzz/PeerTube.git] / support / doc / plugins / guide.md

diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index ea33b8d9f6907f92b20496d9538bb5fa2b2b2946..a90f8e72b2e35c96a1aae4fee4cc4e6b28be17d5 100644 (file)
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -15,17 +15,19 @@
     - [Add custom routes](#add-custom-routes)
     - [Add external auth methods](#add-external-auth-methods)
     - [Add new transcoding profiles](#add-new-transcoding-profiles)
     - [Add custom routes](#add-custom-routes)
     - [Add external auth methods](#add-external-auth-methods)
     - [Add new transcoding profiles](#add-new-transcoding-profiles)

-  - [Helpers](#helpers)
+    - [Server helpers](#server-helpers)

   - [Client API (themes & plugins)](#client-api-themes--plugins)
     - [Plugin static route](#plugin-static-route)
     - [Notifier](#notifier)
     - [Markdown Renderer](#markdown-renderer)
   - [Client API (themes & plugins)](#client-api-themes--plugins)
     - [Plugin static route](#plugin-static-route)
     - [Notifier](#notifier)
     - [Markdown Renderer](#markdown-renderer)

+    - [Auth header](#auth-header)

     - [Custom Modal](#custom-modal)
     - [Translate](#translate)
     - [Get public settings](#get-public-settings)
     - [Get server config](#get-server-config)
     - [Add custom fields to video form](#add-custom-fields-to-video-form)
     - [Register settings script](#register-settings-script)
     - [Custom Modal](#custom-modal)
     - [Translate](#translate)
     - [Get public settings](#get-public-settings)
     - [Get server config](#get-server-config)
     - [Add custom fields to video form](#add-custom-fields-to-video-form)
     - [Register settings script](#register-settings-script)

+    - [HTML placeholder elements](#html-placeholder-elements)

   - [Publishing](#publishing)
 - [Write a plugin/theme](#write-a-plugintheme)
   - [Clone the quickstart repository](#clone-the-quickstart-repository)
   - [Publishing](#publishing)
 - [Write a plugin/theme](#write-a-plugintheme)
   - [Clone the quickstart repository](#clone-the-quickstart-repository)


@@ -194,12 +196,30 @@ Plugins can store/load JSON data, that PeerTube will store in its database (so d
 Example:
 
 ```js
 Example:
 
 ```js

-function register (...) {
+function register ({
+  storageManager
+}) {

   const value = await storageManager.getData('mykey')
   await storageManager.storeData('mykey', { subkey: 'value' })
 }
 ```
 
   const value = await storageManager.getData('mykey')
   await storageManager.storeData('mykey', { subkey: 'value' })
 }
 ```
 

+You can also store files in the plugin data directory (`/{plugins-directory}/data/{npm-plugin-name}`) **in PeerTube >= 3.2**.
+This directory and its content won't be deleted when your plugin is uninstalled/upgraded.
+
+```js
+function register ({
+  storageManager,
+  peertubeHelpers
+}) {
+  const basePath = peertubeHelpers.plugin.getDataDirectoryPath()
+
+  fs.writeFile(path.join(basePath, 'filename.txt'), 'content of my file', function (err) {
+    ...
+  })
+}
+```
+

 #### Update video constants
 
 You can add/delete video categories, licences or languages using the appropriate managers:
 #### Update video constants
 
 You can add/delete video categories, licences or languages using the appropriate managers:


@@ -225,9 +245,27 @@ function register (...) {
 You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
 
 ```js
 You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
 
 ```js

-function register (...) {
+function register ({
+  router
+}) {

   const router = getRouter()
   router.get('/ping', (req, res) => res.json({ message: 'pong' }))
   const router = getRouter()
   router.get('/ping', (req, res) => res.json({ message: 'pong' }))

+
+  // Users are automatically authenticated
+  router.get('/auth', (res, res) => {
+    const user = peertubeHelpers.user.getAuthUser(res)
+
+    const isAdmin = user.role === 0
+    const isModerator = user.role === 1
+    const isUser = user.role === 2
+
+    res.json({
+      username: user.username,
+      isAdmin,
+      isModerator,
+      isUser
+    })
+  })

 }
 ```
 
 }
 ```
 


@@ -341,9 +379,16 @@ async function register ({
       const streamString = streamNum ? ':' + streamNum : ''
 
       // You can also return a promise
       const streamString = streamNum ? ':' + streamNum : ''
 
       // You can also return a promise

-      // All these options are optional and defaults to []
+      // All these options are optional

       return {
       return {

+        scaleFilter: {
+          // Used to define an alternative scale filter, needed by some encoders
+          // Default to 'scale'
+          name: 'scale_vaapi'
+        },
+        // Default to []

         inputOptions: [],
         inputOptions: [],

+        // Default to []

         outputOptions: [
         // Use a custom bitrate
           '-b' + streamString + ' 10K'
         outputOptions: [
         // Use a custom bitrate
           '-b' + streamString + ' 10K'


@@ -417,7 +462,7 @@ async function register ({
 During live transcode input options are applied once for each target resolution.
 Plugins are responsible for detecting such situation and applying input options only once if necessary.
 
 During live transcode input options are applied once for each target resolution.
 Plugins are responsible for detecting such situation and applying input options only once if necessary.
 

-### Helpers
+#### Server helpers

 
 PeerTube provides your plugin some helpers. For example:
 
 
 PeerTube provides your plugin some helpers. For example:
 


@@ -482,6 +527,30 @@ function register (...) {
 }
 ```
 
 }
 ```
 

+#### Auth header
+
+**PeerTube >= 3.2**
+
+To make your own HTTP requests using the current authenticated user, use an helper to automatically set appropriate headers:
+
+```js
+function register (...) {
+  registerHook({
+    target: 'action:auth-user.information-loaded',
+    handler: ({ user }) => {
+
+      // Useless because we have the same info in the ({ user }) parameter
+      // It's just an example
+      fetch('/api/v1/users/me', {
+        method: 'GET',
+        headers: peertubeHelpers.getAuthHeader()
+      }).then(res => res.json())
+        .then(data => console.log('Hi %s.', data.username))
+    }
+  })
+}
+```
+

 #### Custom Modal
 
 To show a custom modal:
 #### Custom Modal
 
 To show a custom modal:


@@ -621,6 +690,21 @@ async function register ({ registerSettingsScript }) {
 }
 ```
 
 }
 ```
 

+#### HTML placeholder elements
+
+PeerTube provides some HTML id so plugins can easily insert their own element:
+
+```js
+async function register (...) {
+  const elem = document.createElement('div')
+  elem.className = 'hello-world-h4'
+  elem.innerHTML = '<h4>Hello everybody! This is an element next to the player</h4>'
+
+  document.getElementById('plugin-placeholder-player-next').appendChild(elem)
+}
+```
+
+See the complete list on https://docs.joinpeertube.org/api-plugins

 
 ### Publishing
 
 
 ### Publishing
 


@@ -721,7 +805,7 @@ If you want to translate strings of your plugin (like labels of your registered
 {
   ...,
   "translations": {
 {
   ...,
   "translations": {

-    "fr-FR": "./languages/fr.json",
+    "fr": "./languages/fr.json",

     "pt-BR": "./languages/pt-BR.json"
   },
   ...
     "pt-BR": "./languages/pt-BR.json"
   },
   ...


@@ -729,7 +813,6 @@ If you want to translate strings of your plugin (like labels of your registered
 ```
 
 The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).
 ```
 
 The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).

-You **must** use the complete locales (`fr-FR` instead of `fr`).

 
 Translation files are just objects, with the english sentence as the key and the translation as the value.
 `fr.json` could contain for example:
 
 Translation files are just objects, with the english sentence as the key and the translation as the value.
 `fr.json` could contain for example: