almost done

2026-08-04 14:37:34 +00:00 · 2025-02-26 15:56:53 -05:00 · 2025-02-26 15:56:53 -05:00 · 1bc144f44e
commit 1bc144f44e
parent 12631d3727
15 changed files with 1921 additions and 46 deletions
--- a/package-lock.json
+++ b/package-lock.json
--- a/src/sdk/README.md
+++ b/src/sdk/README.md
@ -0,0 +1,50 @@
+# Manager SDK Prototype
+
+This is a prototype of a Manager SDK for the Outline Server.
+
+It uses `ngrok` to allow the user to access the Management API from the browser.
+
+It uses the `lit` library to create a web component that displays the server details.
+
+It also uses `@hey-api/openapi-ts` to generate a TypeScript library from the Outline Server API definition.
+
+## Setup
+
+Get a`NGROK_TOKEN` from https://dashboard.ngrok.com/get-started/your-authtoken and a `NGROK_DOMAIN` from https://dashboard.ngrok.com/domains.
+
+```sh
+export NGROK_TOKEN=...
+export NGROK_DOMAIN=...
+
+# Start the local outline server
+task shadowbox:start &
+
+# Start the web app demo
+npm run example --workspace sdk
+```
+
+Result:
+
+<img src="screenshots/results.png" alt="results" width="320"/>
+
+## Library Generation
+
+Generated library from `src/shadowbox/server/api.yml` with `@hey-api/openapi-ts`:
+
+```bash
+# run in project root
+npx @hey-api/openapi-ts \
+  -i src/shadowbox/server/api.yml \
+  -o src/sdk/library/generated \
+  -c @hey-api/client-fetch
+```
+
+Intellisense example:
+
+<img src="screenshots/intellisense.png" alt="intellisense" width="320"/>
+
+## TODOs
+
+- [ ] Why does Prometheus continuously crash (had to comment it out)
+- [ ] Generate Library on API change
+- [ ] ...
--- a/src/sdk/example/index.html
+++ b/src/sdk/example/index.html
@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Manager SDK Demo</title>
+    <script type="module" src="/src/server-details.ts"></script>
+  </head>
+  <body>
+    <server-details url="%VITE_SERVER_DETAIL_URL%"></server-details>
+  </body>
+</html>
--- a/src/sdk/example/src/server-details.ts
+++ b/src/sdk/example/src/server-details.ts
@ -0,0 +1,53 @@
+import { LitElement, html, css } from 'lit'
+import { customElement, state, property } from 'lit/decorators.js';
+
+import makeLibrary, { type Server } from '../../library';
+
+@customElement('server-details')
+export class MainPage extends LitElement {
+  @property({ type: String }) url: string;
+
+  @state() server?: Server;
+
+  constructor(url: string) {
+    super();
+    this.url = url;
+  }
+
+  get client() {
+    return makeLibrary(this.url);
+  }
+
+  static styles = css`
+    :host {
+      font-family: system-ui;
+    }
+
+    dt {
+      font-weight: bold;
+    }
+  `;
+
+  async connectedCallback() {
+    super.connectedCallback();
+
+    const { data } = await this.client.getServer();
+
+    this.server = data;
+  }
+
+  render() {
+    if (!this.server) {
+      return html`Loading...`;
+    }
+
+    return html`
+      <dl>
+        ${Object.entries(this.server).map(([key, value]) => html`
+          <dt>${key}</dt>
+          <dd>${value}</dd>
+        `)}
+      </dl>
+    `;
+  }
+}
--- a/src/sdk/example/src/vite-env.d.ts
+++ b/src/sdk/example/src/vite-env.d.ts
@ -0,0 +1 @@
+/// <reference types="vite/client" />
--- a/src/sdk/example/tsconfig.json
+++ b/src/sdk/example/tsconfig.json
@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}
--- a/src/shadowbox/server/client/client.gen.ts
+++ b/src/shadowbox/server/client/client.gen.ts
--- a/src/shadowbox/server/client/index.ts
+++ b/src/shadowbox/server/client/index.ts
--- a/src/shadowbox/server/client/sdk.gen.ts
+++ b/src/shadowbox/server/client/sdk.gen.ts
--- a/src/shadowbox/server/client/types.gen.ts
+++ b/src/shadowbox/server/client/types.gen.ts
--- a/src/sdk/library/index.ts
+++ b/src/sdk/library/index.ts
@ -0,0 +1,11 @@
+import { client } from './generated/client.gen';
+
+import * as generated from './generated';
+
+export type * from './generated';
+
+export default (baseUrl: string) => {
+  client.setConfig({ baseUrl, headers: { "ngrok-skip-browser-warning": "69420" } });
+
+  return generated;
+}
--- a/src/sdk/package.json
+++ b/src/sdk/package.json
@ -0,0 +1,16 @@
+{
+  "name": "sdk",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "example": "VITE_SERVER_DETAIL_URL=https://${NGROK_DOMAIN}/TestApiPrefix vite example"
+  },
+  "dependencies": {
+    "lit": "^3.2.1"
+  },
+  "devDependencies": {
+    "typescript": "~5.7.2",
+    "vite": "^6.2.0"
+  }
+}
--- a/src/sdk/screenshots/intellisense.png
+++ b/src/sdk/screenshots/intellisense.png
--- a/src/sdk/screenshots/results.png
+++ b/src/sdk/screenshots/results.png
--- a/src/shadowbox/server/main.ts
+++ b/src/shadowbox/server/main.ts
@ -283,17 +283,26 @@ process.on('unhandledRejection', (error: Error) => {

 main()
  .then(async () => {
+    if (!process.env.NGROK_TOKEN || !process.env.NGROK_DOMAIN) {
+      return;
+    }
+
    process.env.SSL_CERT_FILE = process.env.SB_CERTIFICATE_FILE;
    process.env.SSL_KEY_FILE = process.env.SB_PRIVATE_KEY_FILE;

    const listener = await ngrok.forward({
      domain: process.env.NGROK_DOMAIN,
+      // ipv6 loopback address doesn't work
      addr: `https://127.0.0.1:${process.env.SB_API_PORT || 8081}`,
      authtoken_from_env: true,
      verify_upstream_tls: false,
+      response_header_add: [
+        'Allow-Access-Control-Origin: *',
+        'Access-Control-Allow-Headers: *'
+      ],
    });

-    console.log(`Listening to the Manager API on ${listener.url()}`);
+    console.log(`Listening to the Manager API on '${listener.url()}'`);
  })
  .catch((error) => {
    logging.error(error.stack);