docs: update docs

jackdbd · Dec 27, 2022 · 92abb59 · 92abb59
1 parent 24c2077
commit 92abb59
Show file tree

Hide file tree

Showing 44 changed files with 171 additions and 95 deletions.
diff --git a/README.md b/README.md
@@ -43,7 +43,8 @@ npm run build:apps
 Build all docs:
 
 ```sh
-npm run build:docs
+npm run docs
+npm run docs:doctoc
 ```
 
 Generate a file size report for each library:

diff --git a/apps/demo-app/dist/app.js b/apps/demo-app/dist/app.js
@@ -6,6 +6,7 @@ import Inert from '@hapi/inert';
 import Vision from '@hapi/vision';
 import hapi_dev_errors from 'hapi-dev-errors';
 import githubIssue from '@jackdbd/hapi-github-issue-plugin';
+import { defaultTitleFunction, defaultBodyFunction } from '@jackdbd/hapi-github-issue-plugin/texts';
 import logger from '@jackdbd/hapi-logger-plugin';
 import { isServerRequestError, isTeapotRequestError, isUnauthorizedRequestError } from '@jackdbd/hapi-request-event-predicates';
 import telegram from '@jackdbd/hapi-telegram-plugin';
@@ -77,8 +78,26 @@ export const app = async () => {
     server.log(['debug', 'plugin'], {
         message: `plugin ${logger.name} registered`
     });
-    server.register({
-        plugin: githubIssue
+    await server.register({
+        plugin: githubIssue,
+        options: {
+            request_event_matchers: [
+                {
+                    predicate: isServerRequestError,
+                    title: defaultTitleFunction,
+                    body: defaultBodyFunction,
+                    assignees: ['jackdbd'],
+                    labels: ['bug', 'matsuri-test']
+                },
+                {
+                    predicate: isTeapotRequestError,
+                    title: defaultTitleFunction,
+                    body: defaultBodyFunction,
+                    assignees: ['jackdbd'],
+                    labels: ['teapot', 'matsuri-test']
+                }
+            ]
+        }
     });
     server.log(['debug', 'plugin'], {
         message: `plugin ${githubIssue.name} registered`

diff --git a/docs/README.md b/docs/README.md
@@ -5,10 +5,10 @@ The **documentation** for each package is automatically generated by [TypeDoc](h
 
 The **API docs** are generated by [api-extractor](https://api-extractor.com/) + [api-documenter](https://api-extractor.com/pages/setup/generating_docs/).
 
-:warning: Do **not** edit this file manually. This file is generated by `docs-index.mjs` (see [scripts](https://github.com/jackdbd/matsuri/tree/canary/scripts/README.md)).
+:warning: Do **not** edit this file manually. This file is generated by `docs-index.mjs` (see [scripts](https://github.com/jackdbd/matsuri/tree/main/scripts/README.md)).
 
-- [hapi-github-issue-plugin](./hapi-github-issue-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-github-issue-plugin/api-docs/index.md))
-- [hapi-healthcheck-plugin](./hapi-healthcheck-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-healthcheck-plugin/api-docs/index.md))
-- [hapi-logger-plugin](./hapi-logger-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-logger-plugin/api-docs/index.md))
-- [hapi-request-event-predicates](./hapi-request-event-predicates/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-request-event-predicates/api-docs/index.md))
-- [hapi-telegram-plugin](./hapi-telegram-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-telegram-plugin/api-docs/index.md))
+- [hapi-github-issue-plugin](./hapi-github-issue-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-github-issue-plugin/api-docs/index.md))
+- [hapi-healthcheck-plugin](./hapi-healthcheck-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-healthcheck-plugin/api-docs/index.md))
+- [hapi-logger-plugin](./hapi-logger-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-logger-plugin/api-docs/index.md))
+- [hapi-request-event-predicates](./hapi-request-event-predicates/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-request-event-predicates/api-docs/index.md))
+- [hapi-telegram-plugin](./hapi-telegram-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-telegram-plugin/api-docs/index.md))
diff --git a/docs/hapi-github-issue-plugin/assets/highlight.css b/docs/hapi-github-issue-plugin/assets/highlight.css
@@ -15,6 +15,8 @@
     --dark-hl-6: #4FC1FF;
     --light-hl-7: #098658;
     --dark-hl-7: #B5CEA8;
+    --light-hl-8: #008000;
+    --dark-hl-8: #6A9955;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -28,6 +30,7 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
     --code-background: var(--light-code-background);
 } }
 
@@ -40,6 +43,7 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
     --code-background: var(--dark-code-background);
 } }
 
@@ -52,6 +56,7 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
     --code-background: var(--light-code-background);
 }
 
@@ -64,6 +69,7 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
     --code-background: var(--dark-code-background);
 }
 
@@ -75,4 +81,5 @@
 .hl-5 { color: var(--hl-5); }
 .hl-6 { color: var(--hl-6); }
 .hl-7 { color: var(--hl-7); }
+.hl-8 { color: var(--hl-8); }
 pre, code { background: var(--code-background); }
diff --git a/docs/hapi-github-issue-plugin/index.html b/docs/hapi-github-issue-plugin/index.html
@@ -19,7 +19,6 @@ <h1>@jackdbd/hapi-github-issue-plugin</h1>
 <p>Hapi plugin that automatically creates a GitHub issue when a request matches one of the rules you defined.</p>
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-</details>
 
 
 <a href="#installation" id="installation" style="color: inherit; text-decoration: none;">
@@ -36,7 +35,7 @@ <h2>Preliminary Operations</h2>
   <h3>GitHub personal access token</h3>
 </a>
 <p>This Hapi plugin makes a POST request to <code>{{GitHub-API}}/repos/:owner/:repo/issues</code> whenever an HTTP request matches one of the predicates used to configure the plugin itself. To allow this plugin to create an issue in your GitHub repository, you need to configure it with a <a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token">GitHub personal access token</a> with the required <a href="https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps">OAuth scopes</a>. You can reuse an existing personal access token, or create a new one.</p>
-<p><img src="../../assets/images/hapi-github-issue-plugin-oauth-scopes.png" alt="OAuth scopes for the hapi-github-issue-plugin"></p>
+<p><img src="https://raw.githubusercontent.com/jackdbd/matsuri/main/assets/images/hapi-github-issue-plugin-internal-server-error.png" alt="OAuth scopes for the hapi-github-issue-plugin"></p>
 
 <a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
   <h2>Usage</h2>
@@ -45,7 +44,10 @@ <h2>Usage</h2>
 <pre><code class="language-ts"><span class="hl-1">import</span><span class="hl-0"> </span><span class="hl-2">githubIssue</span><span class="hl-0"> </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/hapi-github-issue-plugin&#39;</span><br/><br/><span class="hl-1">export</span><span class="hl-0"> </span><span class="hl-4">const</span><span class="hl-0"> </span><span class="hl-5">app</span><span class="hl-0"> = </span><span class="hl-4">async</span><span class="hl-0"> (</span><span class="hl-2">config</span><span class="hl-0">) </span><span class="hl-4">=&gt;</span><span class="hl-0"> {</span><br/><br/><span class="hl-0">  </span><span class="hl-4">const</span><span class="hl-0"> </span><span class="hl-6">server</span><span class="hl-0"> = </span><span class="hl-2">Hapi</span><span class="hl-0">.</span><span class="hl-5">server</span><span class="hl-0">({ </span><span class="hl-2">port:</span><span class="hl-0"> </span><span class="hl-7">8080</span><span class="hl-0"> })</span><br/><br/><span class="hl-0">  </span><span class="hl-1">await</span><span class="hl-0"> </span><span class="hl-2">server</span><span class="hl-0">.</span><span class="hl-5">register</span><span class="hl-0">({ </span><span class="hl-2">plugin:</span><span class="hl-0"> </span><span class="hl-2">githubIssue</span><span class="hl-0"> })</span><br/><br/><span class="hl-0">  </span><span class="hl-1">return</span><span class="hl-0"> { </span><span class="hl-2">server</span><span class="hl-0"> }</span><br/><span class="hl-0">}</span>
 </code></pre>
 <p>...it will catch any internal server error and create a GitHub issue like this one:</p>
-<p><img src="../../assets/images/hapi-github-issue-plugin-internal-server-error.png" alt="Telegram message about an internal server error in your Hapi app"></p>
+<p><img src="https://raw.githubusercontent.com/jackdbd/matsuri/main/assets/images/hapi-github-issue-plugin-oauth-scopes.png" alt="Telegram message about an internal server error in your Hapi app"></p>
+<p>You can create a GitHub issue for any kind of request handled by yout Hapi application, as long as you define a request matcher for it. For example, here I configure the plugin to create an issue every time the Hapi app responds with <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500">HTTP 500 internal server error</a>, or when it responds with <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/418">HTTP 418 I&#39;m a Teapot</a>.</p>
+<pre><code class="language-ts"><span class="hl-8">// import the plugin itself</span><br/><span class="hl-1">import</span><span class="hl-0"> </span><span class="hl-2">githubIssue</span><span class="hl-0"> </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/hapi-github-issue-plugin&#39;</span><br/><br/><span class="hl-8">// define the functions that create the issue title/body somewhere</span><br/><span class="hl-8">// in your app, or import them from a library.</span><br/><span class="hl-1">import</span><span class="hl-0"> {</span><br/><span class="hl-0">  </span><span class="hl-2">defaultTitleFunction</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-2">defaultBodyFunction</span><br/><span class="hl-0">} </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/hapi-github-issue-plugin/texts&#39;</span><br/><br/><span class="hl-8">// define your request predicates somewhere in your app,</span><br/><span class="hl-8">// or import them from a library.</span><br/><span class="hl-1">import</span><span class="hl-0"> {</span><br/><span class="hl-0">  </span><span class="hl-2">isServerRequestError</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-2">isUnauthorizedRequestError</span><br/><span class="hl-0">} </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/hapi-request-event-predicates&#39;</span><br/><br/><span class="hl-1">export</span><span class="hl-0"> </span><span class="hl-4">const</span><span class="hl-0"> </span><span class="hl-5">app</span><span class="hl-0"> = </span><span class="hl-4">async</span><span class="hl-0"> (</span><span class="hl-2">config</span><span class="hl-0">) </span><span class="hl-4">=&gt;</span><span class="hl-0"> {</span><br/><br/><span class="hl-0">  </span><span class="hl-4">const</span><span class="hl-0"> </span><span class="hl-6">server</span><span class="hl-0"> = </span><span class="hl-2">Hapi</span><span class="hl-0">.</span><span class="hl-5">server</span><span class="hl-0">({ </span><span class="hl-2">port:</span><span class="hl-0"> </span><span class="hl-7">8080</span><span class="hl-0"> })</span><br/><br/><span class="hl-0">  </span><span class="hl-1">await</span><span class="hl-0"> </span><span class="hl-2">server</span><span class="hl-0">.</span><span class="hl-5">register</span><span class="hl-0">({</span><br/><span class="hl-0">    </span><span class="hl-2">plugin:</span><span class="hl-0"> </span><span class="hl-2">githubIssue</span><span class="hl-0">,</span><br/><span class="hl-0">    </span><span class="hl-2">options:</span><span class="hl-0"> {</span><br/><span class="hl-0">      </span><span class="hl-2">request_event_matchers:</span><span class="hl-0"> [</span><br/><span class="hl-0">        </span><span class="hl-8">// create an issues every time the Hapi app responds with</span><br/><span class="hl-0">        </span><span class="hl-8">// HTTP 500 Internal Server Error, and assign it to bob.</span><br/><span class="hl-0">        {</span><br/><span class="hl-0">          </span><span class="hl-2">predicate:</span><span class="hl-0"> </span><span class="hl-2">isServerRequestError</span><span class="hl-0">,</span><br/><span class="hl-0">          </span><span class="hl-2">title:</span><span class="hl-0"> </span><span class="hl-2">defaultTitleFunction</span><span class="hl-0">,</span><br/><span class="hl-0">          </span><span class="hl-2">body:</span><span class="hl-0"> </span><span class="hl-2">defaultBodyFunction</span><span class="hl-0">,</span><br/><span class="hl-0">          </span><span class="hl-2">assignees:</span><span class="hl-0"> [</span><span class="hl-3">&#39;bob&#39;</span><span class="hl-0">],</span><br/><span class="hl-0">          </span><span class="hl-2">labels:</span><span class="hl-0"> [</span><span class="hl-3">&#39;bug&#39;</span><span class="hl-0">, </span><span class="hl-3">&#39;matsuri-test&#39;</span><span class="hl-0">]</span><br/><span class="hl-0">        },</span><br/><span class="hl-0">        </span><span class="hl-8">// create an issues every time the Hapi app responds with</span><br/><span class="hl-0">        </span><span class="hl-8">// HTTP 418 I&#39;m a teapot, and assign it to john.</span><br/><span class="hl-0">        {</span><br/><span class="hl-0">          </span><span class="hl-2">predicate:</span><span class="hl-0"> </span><span class="hl-2">isTeapotRequestError</span><span class="hl-0">,</span><br/><span class="hl-0">          </span><span class="hl-2">title:</span><span class="hl-0"> </span><span class="hl-2">defaultTitleFunction</span><span class="hl-0">,</span><br/><span class="hl-0">          </span><span class="hl-2">body:</span><span class="hl-0"> </span><span class="hl-2">defaultBodyFunction</span><span class="hl-0">,</span><br/><span class="hl-0">          </span><span class="hl-2">assignees:</span><span class="hl-0"> [</span><span class="hl-3">&#39;john&#39;</span><span class="hl-0">],</span><br/><span class="hl-0">          </span><span class="hl-2">labels:</span><span class="hl-0"> [</span><span class="hl-3">&#39;teapot&#39;</span><span class="hl-0">, </span><span class="hl-3">&#39;matsuri-test&#39;</span><span class="hl-0">]</span><br/><span class="hl-0">        }</span><br/><span class="hl-0">      ]</span><br/><span class="hl-0">    }</span><br/><span class="hl-0">  })</span><br/><br/><span class="hl-0">  </span><span class="hl-1">return</span><span class="hl-0"> { </span><span class="hl-2">server</span><span class="hl-0"> }</span><br/><span class="hl-0">}</span>
+</code></pre>
 
 <a href="#configuration" id="configuration" style="color: inherit; text-decoration: none;">
   <h2>Configuration</h2>