@karmaniverous/jeeves-server 3.0.0-1 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +36 -22
  2. package/README.md +45 -0
  3. package/about.md +15 -39
  4. package/guides/api-integration.md +62 -155
  5. package/guides/deployment.md +60 -164
  6. package/guides/event-gateway.md +46 -50
  7. package/guides/exports.md +18 -20
  8. package/guides/index.md +21 -0
  9. package/guides/setup.md +211 -181
  10. package/guides/sharing.md +7 -7
  11. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,8 +2,10 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file. Dates are displayed in UTC.
4
4
 
5
- #### [v3.0.0-1](https://github.com/karmaniverous/jeeves-server/compare/v2.9.3...v3.0.0-1)
5
+ #### [v3.0.1](https://github.com/karmaniverous/jeeves-server/compare/v2.9.3...v3.0.1)
6
6
 
7
+ - docs: guide index content + typedoc jsonl highlight [`#86`](https://github.com/karmaniverous/jeeves-server/pull/86)
8
+ - docs: refresh README + guides for v3 [`#85`](https://github.com/karmaniverous/jeeves-server/pull/85)
7
9
  - feat: named access scopes [`#84`](https://github.com/karmaniverous/jeeves-server/pull/84)
8
10
  - fix: plugin auth chain, status endpoint improvements [`#83`](https://github.com/karmaniverous/jeeves-server/pull/83)
9
11
  - fix: resetConfig should reload, not clear [`#82`](https://github.com/karmaniverous/jeeves-server/pull/82)
@@ -29,53 +31,65 @@ All notable changes to this project will be documented in this file. Dates are d
29
31
  - chore: add default port 1934 [`#62`](https://github.com/karmaniverous/jeeves-server/pull/62)
30
32
  - chore: add default port 1934 [`#61`](https://github.com/karmaniverous/jeeves-server/pull/61)
31
33
  - chore: add client as workspace member, align puppeteer versions [`6e3a40d`](https://github.com/karmaniverous/jeeves-server/commit/6e3a40dfdb91ffe2e39877d1b69b36db3e01f863)
34
+ - updated docs [`86d88c7`](https://github.com/karmaniverous/jeeves-server/commit/86d88c76b04b32132195370328f434b427b7e23d)
35
+ - updated docs [`cbd8537`](https://github.com/karmaniverous/jeeves-server/commit/cbd853764a9b5953afb847aa653a5182f74b1cd6)
36
+ - docs: refresh README and guides for v3 CLI + config [`e437387`](https://github.com/karmaniverous/jeeves-server/commit/e4373875d454518b8f4d8dcf37613ddc36f2aace)
37
+ - fix: resolve all client ESLint errors and warnings [`768541a`](https://github.com/karmaniverous/jeeves-server/commit/768541a71644c3ddcbc4a50bc6ed7a42a1c6d9a5)
38
+ - chore: release @karmaniverous/jeeves-server v3.0.0-0 [`07a6e47`](https://github.com/karmaniverous/jeeves-server/commit/07a6e475a08ccd485765bfaa535f9d63cb8bb42a)
39
+ - fix: resolve knip unused files, dependencies, and exports [`964beba`](https://github.com/karmaniverous/jeeves-server/commit/964beba273f99be8d3302648c2dd442a3e3dcc07)
40
+ - chore: release @karmaniverous/jeeves-server-openclaw v0.1.0-0 [`b6c0f6d`](https://github.com/karmaniverous/jeeves-server/commit/b6c0f6db6ab8bbdcffb40affc00f9f573ca2caa5)
41
+ - docs: add typedoc config and dependencies [`761bb8c`](https://github.com/karmaniverous/jeeves-server/commit/761bb8cef7c5d84f17c9193d688bd9b0be67a6ca)
42
+ - npm audit fix [`3a144b4`](https://github.com/karmaniverous/jeeves-server/commit/3a144b4b07e1387cf40733486e60aeaf7a34d0a6)
43
+ - docs: add guide index content and fix typedoc trailing comma [`3844271`](https://github.com/karmaniverous/jeeves-server/commit/3844271f0aacc6eb0af7dc6ddabe139edae95332)
44
+ - chore: add knip configs, remove dead exports, clean all code quality checks [`2a81072`](https://github.com/karmaniverous/jeeves-server/commit/2a81072cc5341047b2ef40333405a8cc9760dab4)
45
+ - fix: make resetConfig reload runtime config [`79e8602`](https://github.com/karmaniverous/jeeves-server/commit/79e8602b4a8ee13c4de94bb3d262dd8bdb7cd2c8)
46
+ - updated docs [`075a6f3`](https://github.com/karmaniverous/jeeves-server/commit/075a6f36cee6279c83ba564e6efbde99ebac2f37)
47
+ - npm audit fix [`3810c0f`](https://github.com/karmaniverous/jeeves-server/commit/3810c0fad8067752c4513bcccdd721698c8b3c3b)
48
+ - lintfix [`00dc2b2`](https://github.com/karmaniverous/jeeves-server/commit/00dc2b2ec30ea2a4365d93b86c66330b831737a7)
49
+ - ni [`e40deac`](https://github.com/karmaniverous/jeeves-server/commit/e40deacf8659a59328ceec50abb6f1f27041b5d8)
50
+ - docs: add changelogs as children of package guide indexes [`fd16b5b`](https://github.com/karmaniverous/jeeves-server/commit/fd16b5b7f80ad2b58d883fe3b7cf270668026f8e)
51
+ - lintfix [`38a9376`](https://github.com/karmaniverous/jeeves-server/commit/38a937631ab2ac3c22240857f69b36d5d9570665)
52
+ - chore: release @karmaniverous/jeeves-server v3.0.0-1 [`db96bc1`](https://github.com/karmaniverous/jeeves-server/commit/db96bc140b9cbca7ad52ddd562a805ac74ca67aa)
53
+ - fix: resolve TS2352 warnings in openclaw test mocks [`88950e2`](https://github.com/karmaniverous/jeeves-server/commit/88950e23bbd206e40a7bc25ea35c64d7609af281)
54
+ - fix: CI failures and SvgViewer panzoom re-init bug [`7392712`](https://github.com/karmaniverous/jeeves-server/commit/73927128276341a37c362c3143334bd8bb416d09)
55
+ - fix: resolve remaining lint errors (type annotations, unused params, unnecessary conditionals) [`e7714ae`](https://github.com/karmaniverous/jeeves-server/commit/e7714ae451a72a1dd9881d85c964d6d8aec17574)
56
+ - fix: remove unnecessary auth from /api/status calls (endpoint is public) [`f651fe7`](https://github.com/karmaniverous/jeeves-server/commit/f651fe7bff4320eb28b5039278bcdcd032cac6d5)
57
+ - chore: release @karmaniverous/jeeves-server-openclaw v0.1.0-1 [`d08e571`](https://github.com/karmaniverous/jeeves-server/commit/d08e571d58bb6387e69441dc06511d92fb743c15)
58
+ - fix: CI rimraf resolution and remove redundant client steps [`757c45c`](https://github.com/karmaniverous/jeeves-server/commit/757c45cf429e7c70358442e353922f7999d74640)
59
+ - chore: release @karmaniverous/jeeves-server v3.0.0 [`ef408c3`](https://github.com/karmaniverous/jeeves-server/commit/ef408c37ee306417ee24d58b256cba672f7984c1)
60
+ - chore: release @karmaniverous/jeeves-server-openclaw v0.1.0 [`bbeac17`](https://github.com/karmaniverous/jeeves-server/commit/bbeac17333ebad423b0fd8c2bcd310bbb0b63b27)
61
+ - npm audit fix [`2f3b5c8`](https://github.com/karmaniverous/jeeves-server/commit/2f3b5c89af0bf56b17fd37719f5927812f2c8e24)
62
+ - publishconfig public access [`8e4358c`](https://github.com/karmaniverous/jeeves-server/commit/8e4358cc43dc2f131840047d34f2644eb6293fe2)
63
+ - fix: add pattern to StatusResponse events type [`f64e6af`](https://github.com/karmaniverous/jeeves-server/commit/f64e6af06ce51a54dee4bf69dd0e6fbae79dc683)
64
+ - fix: normalize path for watcher render (Windows backslash + uppercase drive) [`f6c229d`](https://github.com/karmaniverous/jeeves-server/commit/f6c229d7f4ac7ec11099c884b75e6a90cc0cdf59)
65
+ - zero version [`2c0db75`](https://github.com/karmaniverous/jeeves-server/commit/2c0db75d547d812fa638e15f2da732a7b91ad69c)
66
+ - merge: incorporate main (PR #77 gap-analysis) [`845268d`](https://github.com/karmaniverous/jeeves-server/commit/845268de8d3b990187f078f0135053d52c311009)
32
67
  - feat: internalize diagram dependencies (mermaid/plantuml) [`9c7f8a7`](https://github.com/karmaniverous/jeeves-server/commit/9c7f8a7d331a4e4f6013f1c7c2fff373769c6fbb)
33
68
  - feat: implement OpenClaw plugin (Phase 3, Steps 11-15) [`72a04e0`](https://github.com/karmaniverous/jeeves-server/commit/72a04e030352ca105c160b331328863c9ce41058)
34
69
  - refactor: monorepo scaffolding (Phase 1, Step 1) [`15cf2ba`](https://github.com/karmaniverous/jeeves-server/commit/15cf2baa7079057f095c973932d233dda2013659)
35
70
  - feat: migrate config from jiti/TS to cosmiconfig/JSON [`adfba33`](https://github.com/karmaniverous/jeeves-server/commit/adfba3387219d49f4675a6c6579253d563788394)
36
- - fix: resolve all client ESLint errors and warnings [`768541a`](https://github.com/karmaniverous/jeeves-server/commit/768541a71644c3ddcbc4a50bc6ed7a42a1c6d9a5)
37
- - chore: release @karmaniverous/jeeves-server v3.0.0-0 [`07a6e47`](https://github.com/karmaniverous/jeeves-server/commit/07a6e475a08ccd485765bfaa535f9d63cb8bb42a)
38
71
  - chore: SOLID/DRY pass #3 + plugin test coverage [`7dcc4c3`](https://github.com/karmaniverous/jeeves-server/commit/7dcc4c3ad36a45a46dc99c8a1e749dfd2ec01e47)
39
72
  - feat: add CLI commands (start, config validate/show, service) [`0437984`](https://github.com/karmaniverous/jeeves-server/commit/0437984e7f783604f9cbdd333db61f8d1af42961)
40
- - fix: resolve knip unused files, dependencies, and exports [`964beba`](https://github.com/karmaniverous/jeeves-server/commit/964beba273f99be8d3302648c2dd442a3e3dcc07)
41
- - chore: release @karmaniverous/jeeves-server-openclaw v0.1.0-0 [`b6c0f6d`](https://github.com/karmaniverous/jeeves-server/commit/b6c0f6db6ab8bbdcffb40affc00f9f573ca2caa5)
42
73
  - fix: address all gap analysis findings [`1eb02ab`](https://github.com/karmaniverous/jeeves-server/commit/1eb02abf0634be38c687d4927a2360cd27c3aad8)
43
- - npm audit fix [`3a144b4`](https://github.com/karmaniverous/jeeves-server/commit/3a144b4b07e1387cf40733486e60aeaf7a34d0a6)
44
74
  - feat: add GET /api/link-info endpoint [`02ece39`](https://github.com/karmaniverous/jeeves-server/commit/02ece3960aa91861455034aa4bfe8850c0b0f363)
45
75
  - test: add resolve.ts unit tests (21 tests) [`7c988ef`](https://github.com/karmaniverous/jeeves-server/commit/7c988ef08a45e5d6f3d04165f01b718a8bb539a6)
46
76
  - fix: cosmiconfig searchPlaces, SOLID/DRY pass, test coverage [`08de751`](https://github.com/karmaniverous/jeeves-server/commit/08de751a26fe595f13d43970bb39bb8b4d609199)
47
77
  - feat: add GET /api/status endpoint [`764c3a7`](https://github.com/karmaniverous/jeeves-server/commit/764c3a7313bd895032cc17bdc811808cdc8eb80e)
48
78
  - chore: SOLID/DRY/test coverage pass [`e491bfb`](https://github.com/karmaniverous/jeeves-server/commit/e491bfbbce7fef13252c2488378b85e983a2207a)
49
79
  - refactor: extract buildRuntimeConfig to resolve.ts (DRY) [`87bd749`](https://github.com/karmaniverous/jeeves-server/commit/87bd749c6827e3c95e2ff9996ab1b781cb316932)
50
- - chore: add knip configs, remove dead exports, clean all code quality checks [`2a81072`](https://github.com/karmaniverous/jeeves-server/commit/2a81072cc5341047b2ef40333405a8cc9760dab4)
51
80
  - fix: address Gemini code review feedback across PRs #65-#76 [`2fef919`](https://github.com/karmaniverous/jeeves-server/commit/2fef9192b00c80605c9cca348ea7feff5af2602a)
52
- - fix: make resetConfig reload runtime config [`79e8602`](https://github.com/karmaniverous/jeeves-server/commit/79e8602b4a8ee13c4de94bb3d262dd8bdb7cd2c8)
53
81
  - refactor: extract shared renderMarkdownContent pipeline [`244dddf`](https://github.com/karmaniverous/jeeves-server/commit/244dddf83da846d2863e776ae78a029610532d2d)
54
82
  - feat: schema-driven search facet filters (Step 10) [`c305c2a`](https://github.com/karmaniverous/jeeves-server/commit/c305c2ae261514411b6329bdc84052ee5c189759)
55
83
  - feat: add scroll anchoring for async diagram renders [`e4bd972`](https://github.com/karmaniverous/jeeves-server/commit/e4bd97293dbb8a9a63d5cf3bceb6e0cbb7a26916)
56
84
  - feat: document rendering pipeline (Phase 4, Steps 16-18) [`56095ee`](https://github.com/karmaniverous/jeeves-server/commit/56095ee8f7153509048f0b8af1ed73bb95aa5ae0)
57
- - npm audit fix [`3810c0f`](https://github.com/karmaniverous/jeeves-server/commit/3810c0fad8067752c4513bcccdd721698c8b3c3b)
58
- - lintfix [`00dc2b2`](https://github.com/karmaniverous/jeeves-server/commit/00dc2b2ec30ea2a4365d93b86c66330b831737a7)
59
85
  - fix: resolve package.json path portably for version [`29d775c`](https://github.com/karmaniverous/jeeves-server/commit/29d775c318ee85003fd6be7f67303633e092a110)
60
86
  - feat: add GET /api/search/facets proxy endpoint [`28fc200`](https://github.com/karmaniverous/jeeves-server/commit/28fc20084453b7bee28b4b9b23932a85a88567d0)
61
- - ni [`e40deac`](https://github.com/karmaniverous/jeeves-server/commit/e40deacf8659a59328ceec50abb6f1f27041b5d8)
62
- - lintfix [`38a9376`](https://github.com/karmaniverous/jeeves-server/commit/38a937631ab2ac3c22240857f69b36d5d9570665)
63
87
  - chore: migrate default port to 1934 [`4614a5f`](https://github.com/karmaniverous/jeeves-server/commit/4614a5f4a5a1fd1d75eb730adbb8caa4a7dab7ff)
64
88
  - chore: add tsdoc.json to both package roots [`9ccf217`](https://github.com/karmaniverous/jeeves-server/commit/9ccf2171347ed4deabe617b16b236edba5b5bc75)
65
89
  - chore: add tsdoc.json to both package roots [`173cf94`](https://github.com/karmaniverous/jeeves-server/commit/173cf94061cfabd3c21796cb10ad0300c1e14e2b)
66
90
  - fix: set rootDir and update start script path for monorepo layout [`a2fd77c`](https://github.com/karmaniverous/jeeves-server/commit/a2fd77cb067fbae733a64e9bc04c0d9159910f90)
67
- - fix: resolve TS2352 warnings in openclaw test mocks [`88950e2`](https://github.com/karmaniverous/jeeves-server/commit/88950e23bbd206e40a7bc25ea35c64d7609af281)
68
- - fix: CI failures and SvgViewer panzoom re-init bug [`7392712`](https://github.com/karmaniverous/jeeves-server/commit/73927128276341a37c362c3143334bd8bb416d09)
69
- - fix: resolve remaining lint errors (type annotations, unused params, unnecessary conditionals) [`e7714ae`](https://github.com/karmaniverous/jeeves-server/commit/e7714ae451a72a1dd9881d85c964d6d8aec17574)
70
- - fix: remove unnecessary auth from /api/status calls (endpoint is public) [`f651fe7`](https://github.com/karmaniverous/jeeves-server/commit/f651fe7bff4320eb28b5039278bcdcd032cac6d5)
71
91
  - fix: update linux-compat CI for monorepo paths [`22dd30f`](https://github.com/karmaniverous/jeeves-server/commit/22dd30ffe5543042287a299523e5b1125c86381e)
72
92
  - chore: eliminate all lint warnings [`ed12c86`](https://github.com/karmaniverous/jeeves-server/commit/ed12c868546a3f14f7d809d7378235ac91415be7)
73
- - fix: CI rimraf resolution and remove redundant client steps [`757c45c`](https://github.com/karmaniverous/jeeves-server/commit/757c45cf429e7c70358442e353922f7999d74640)
74
- - publishconfig public access [`8e4358c`](https://github.com/karmaniverous/jeeves-server/commit/8e4358cc43dc2f131840047d34f2644eb6293fe2)
75
- - fix: add pattern to StatusResponse events type [`f64e6af`](https://github.com/karmaniverous/jeeves-server/commit/f64e6af06ce51a54dee4bf69dd0e6fbae79dc683)
76
- - fix: normalize path for watcher render (Windows backslash + uppercase drive) [`f6c229d`](https://github.com/karmaniverous/jeeves-server/commit/f6c229d7f4ac7ec11099c884b75e6a90cc0cdf59)
77
- - zero version [`2c0db75`](https://github.com/karmaniverous/jeeves-server/commit/2c0db75d547d812fa638e15f2da732a7b91ad69c)
78
- - merge: incorporate main (PR #77 gap-analysis) [`845268d`](https://github.com/karmaniverous/jeeves-server/commit/845268de8d3b990187f078f0135053d52c311009)
79
93
  - fix: add missing return-await in facets handler [`b08d4a3`](https://github.com/karmaniverous/jeeves-server/commit/b08d4a34b1bc2a648edf4e9aeb23d4db0be45afc)
80
94
  - fix: remove unused parameter in linkInfo test [`36fca9a`](https://github.com/karmaniverous/jeeves-server/commit/36fca9ad8e051a47902ce75dab360ac98c169321)
81
95
  - ci: add Node 24 to linux-compat matrix [`66f1008`](https://github.com/karmaniverous/jeeves-server/commit/66f1008c133f2543181636200f49979878925a05)
package/README.md ADDED
@@ -0,0 +1,45 @@
1
+ # @karmaniverous/jeeves-server
2
+
3
+ Jeeves Server — secure file browser, markdown viewer, and webhook gateway with PDF/DOCX export and expiring share links.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install -g @karmaniverous/jeeves-server
9
+ ```
10
+
11
+ ## Run
12
+
13
+ Jeeves Server loads configuration via cosmiconfig. Create a config file such as `jeeves-server.config.json` and run:
14
+
15
+ ```bash
16
+ jeeves-server start [--config <path>]
17
+ ```
18
+
19
+ Default port: **1934**.
20
+
21
+ ## CLI
22
+
23
+ ```bash
24
+ jeeves-server start
25
+ jeeves-server config validate
26
+ jeeves-server config show
27
+ jeeves-server service install
28
+ jeeves-server service uninstall
29
+ jeeves-server service start|stop|restart
30
+ ```
31
+
32
+ ## Docs
33
+
34
+ - Setup & Configuration: ../../packages/service/guides/setup.md
35
+ - Deployment: ../../packages/service/guides/deployment.md
36
+ - Sharing: ../../packages/service/guides/sharing.md
37
+ - Exports: ../../packages/service/guides/exports.md
38
+ - Event Gateway: ../../packages/service/guides/event-gateway.md
39
+ - API Integration: ../../packages/service/guides/api-integration.md
40
+
41
+ ## Public endpoints
42
+
43
+ - `GET /health` — health check
44
+ - `GET /api/status` — server metadata (public; no auth)
45
+
package/about.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Jeeves Server
2
2
 
3
- A lightweight file browser and document viewer with secure, shareable links.
3
+ A self-hosted file browser, document viewer, and webhook gateway with secure sharing and one-click PDF/DOCX export.
4
4
 
5
5
  ## Why Markdown?
6
6
 
@@ -8,38 +8,38 @@ A lightweight file browser and document viewer with secure, shareable links.
8
8
 
9
9
  But in the business world, you can't share `.md` files — people expect PDFs and Word documents.
10
10
 
11
- **Jeeves Server bridges this gap.** Author your documents in Markdown, review them beautifully rendered in the browser, then export to PDF or DOCX with one click when it's time to share with colleagues, clients, or stakeholders.
11
+ **Jeeves Server bridges this gap.** Author your documents in Markdown, review them beautifully rendered in the browser, then export to PDF or DOCX with one click when it's time to share.
12
12
 
13
13
  ## Features
14
14
 
15
- - **File Browser** — Navigate your filesystem through a web interface
15
+ - **File Browser** — Navigate your filesystem through a modern web interface
16
16
  - **Markdown Rendering** — `.md` files render as styled HTML with table of contents
17
17
  - **PDF & DOCX Export** — One-click export for business-ready documents
18
18
  - **Code Highlighting** — Source files display with syntax highlighting
19
+ - **Mermaid & PlantUML Diagrams** — Rendered inline with pan/zoom
19
20
  - **Dark/Light Themes** — Toggle between themes; preference is saved
20
21
  - **Secure Sharing** — Generate expiring links for external recipients
22
+ - **Semantic Search** — Full-text search across indexed documents (via jeeves-watcher integration)
21
23
 
22
24
  ## Authentication
23
25
 
24
- Jeeves uses **path-specific keys** for authentication. There are two access modes:
26
+ Jeeves uses two access modes:
25
27
 
26
28
  ### Insider Access
27
29
 
28
- Insider links use a single master key that works for any path. With insider access you can:
30
+ Insider links use a derived key that works within configured scopes. With insider access you can:
29
31
 
30
- - Navigate freely between directories and files
32
+ - Navigate freely between directories and files (within scopes)
31
33
  - Generate shareable links for others
32
- - Rotate the API key (invalidates all existing links)
34
+ - Rotate your API key (invalidates all existing links)
35
+ - Search across indexed documents
33
36
 
34
37
  ### Outsider Access
35
38
 
36
39
  Outsider links are path-specific and can optionally expire. With outsider access you can:
37
40
 
38
41
  - View the specific file or directory shared with you
39
- - Download raw files
40
- - Share the same link with others
41
-
42
- Outsiders cannot navigate to parent directories or other paths.
42
+ - Download raw files and exports
43
43
 
44
44
  ## Header Controls
45
45
 
@@ -47,36 +47,12 @@ Outsiders cannot navigate to parent directories or other paths.
47
47
  |--------|-------------|
48
48
  | 🎩 | Home — return to drive list (insider only) |
49
49
  | ? | About — this page |
50
- | 🔑 | Rotate API Key — generates a new master key, invalidating all existing links |
51
- | ⬇ Raw | Download the raw file |
52
- | 📄 PDF | Export markdown as PDF |
53
- | 📝 DOCX | Export markdown as Word document |
54
- | Inside | Copy insider link to clipboard |
55
- | Outside | Generate outsider link (optionally with expiry) |
50
+ | 🔑 | Rotate API Key — generates a new key, invalidating all existing links |
51
+ | ⬇ | Download/Export — raw file, PDF, DOCX, or ZIP |
52
+ | 🔗 | Share — copy insider or outsider link with optional expiry |
53
+ | 🔎 | Search — semantic search across indexed documents |
56
54
  | 🌙/☀️ | Toggle dark/light theme |
57
55
 
58
- ## Sharing Links
59
-
60
- ### Insider Links
61
-
62
- Click **Inside** to copy the current page URL with insider access. Anyone with this link can navigate freely.
63
-
64
- ### Outsider Links
65
-
66
- 1. Enter an expiry in the input field (e.g., `15m`, `1h`, `7d`) or leave blank for no expiry
67
- 2. Click **Outside** to generate and copy a path-specific link
68
- 3. Share the link — recipients can only view this specific path
69
-
70
- ## Key Rotation
71
-
72
- Click the 🔑 button to rotate the API key. This will:
73
-
74
- - Generate a new random API key
75
- - Invalidate **all** existing insider and outsider links
76
- - Redirect you to the same page with the new insider key
77
-
78
- The time since last rotation is shown next to the key button.
79
-
80
56
  ---
81
57
 
82
58
  *Jeeves Server — [GitHub](https://github.com/karmaniverous/jeeves-server)*
package/guides/api-integration.md CHANGED
@@ -4,15 +4,15 @@ How to interact with Jeeves Server programmatically — for scripts, bots, AI as
4
4
 
5
5
  ## Authentication for API Access
6
6
 
7
- All API requests authenticate via `?key=<insider-key>` URL parameter or session cookie. For programmatic access, use a key:
8
-
9
- ```typescript
10
- // In jeeves.config.ts
11
- keys: {
12
- 'ci-bot': 'random-seed-string',
13
- // Scoped key for webhooks only:
14
- 'webhook': { key: 'another-seed', scopes: ['/event'] },
15
- },
7
+ All API requests (except `/health` and `/api/status`) authenticate via `?key=<insider-key>` URL parameter or session cookie.
8
+
9
+ ```json
10
+ {
11
+ "keys": {
12
+ "ci-bot": "random-seed-string",
13
+ "webhook": { "key": "another-seed", "scopes": ["/event"] }
14
+ }
15
+ }
16
16
  ```
17
17
 
18
18
  ### Getting the derived key
@@ -20,7 +20,6 @@ keys: {
20
20
  The config contains **seeds**. The actual URL key is derived via HMAC:
21
21
 
22
22
  ```bash
23
- # Get the insider key from a seed
24
23
  curl -s "http://localhost:1934/insider-key" -H "X-API-Key: <seed>"
25
24
  # Returns: { "key": "a1b2c3d4..." }
26
25
  ```
@@ -36,118 +35,78 @@ function insiderKey(seed) {
36
35
 
37
36
  ## API Endpoints
38
37
 
39
- ### File Access
38
+ ### Public (no auth required)
40
39
 
41
- ```bash
42
- # Get file content (rendered)
43
- GET /api/file/d/docs/design.md?key=<key>
44
- # Returns: { type: "markdown", html: "...", headings: [...], content: "...", fileName: "..." }
40
+ | Method | Path | Description |
41
+ |--------|------|-------------|
42
+ | `GET` | `/health` | Simple health check (200 OK) |
43
+ | `GET` | `/api/status` | Server metadata: version, uptime, services, capabilities |
45
44
 
46
- # Get file content (raw text)
47
- GET /api/file/d/docs/design.md?key=<key>&mode=raw
48
- # Returns: { type: "text", content: "...", fileName: "..." }
45
+ ### File Access (auth required)
49
46
 
50
- # Get raw file bytes
51
- GET /path/d/docs/design.md?key=<key>&raw=1
52
- # Returns: file content with appropriate Content-Type
47
+ | Method | Path | Description |
48
+ |--------|------|-------------|
49
+ | `GET` | `/api/file/<path>` | File content (rendered HTML for markdown, raw for others) |
50
+ | `GET` | `/api/raw/<path>` | Raw file bytes with appropriate Content-Type |
51
+ | `GET` | `/api/link-info/<path>` | Query available views and export formats for a path |
53
52
 
54
- # Export as PDF
55
- GET /path/d/docs/design.md?key=<key>&export=pdf
56
- # Returns: application/pdf
53
+ ### Directory Access
57
54
 
58
- # Export as DOCX
59
- GET /path/d/docs/design.md?key=<key>&export=docx
60
- # Returns: application/vnd.openxmlformats-officedocument.wordprocessingml.document
61
- ```
55
+ | Method | Path | Description |
56
+ |--------|------|-------------|
57
+ | `GET` | `/api/drives` | List available drives (Windows) or roots (Linux) |
58
+ | `GET` | `/api/directory/<path>` | List directory contents |
62
59
 
63
- ### Directory Listing
60
+ ### Export
64
61
 
65
- ```bash
66
- # List drives
67
- GET /api/drives?key=<key>
68
- # Returns: { drives: [{ letter: "C", label: "System", ... }] }
62
+ | Method | Path | Description |
63
+ |--------|------|-------------|
64
+ | `GET` | `/api/export/<path>?format=pdf\|docx\|zip` | Export file or directory |
65
+ | `GET` | `/api/mermaid-export/<path>?format=svg\|png\|pdf` | Export Mermaid diagram |
66
+ | `GET` | `/api/plantuml-export/<path>?format=svg\|png\|pdf\|eps` | Export PlantUML diagram |
69
67
 
70
- # List directory
71
- GET /api/directory/d/docs?key=<key>
72
- # Returns: { path: "d/docs", entries: [{ name: "...", type: "file"|"directory", ... }] }
73
- ```
68
+ ### Sharing
74
69
 
75
- ### Authentication
70
+ | Method | Path | Description |
71
+ |--------|------|-------------|
72
+ | `GET` | `/insider-key` | Get derived insider key (requires `X-API-Key` header with seed) |
73
+ | `GET` | `/key?path=<path>` | Compute outsider key for a path |
74
+ | `POST` | `/rotate-key` | Rotate an insider's key (invalidates all their outsider links) |
76
75
 
77
- ```bash
78
- # Check auth status
79
- GET /api/auth/status?key=<key>
80
- # Returns: { authenticated: true, email: "...", isInsider: true, mode: "key" }
81
- ```
76
+ ### Authentication
82
77
 
83
- ### Sharing
84
-
85
- ```bash
86
- # Get insider key (requires X-API-Key header with seed)
87
- GET /insider-key
88
- # Headers: X-API-Key: <seed>
89
- # Returns: { key: "a1b2c3d4..." }
90
-
91
- # Compute outsider key for a path
92
- GET /key?path=/d/docs/design.md
93
- # Headers: X-API-Key: <seed>
94
- # Returns: { key: "e5f6a7b8..." }
95
-
96
- # Rotate a key
97
- POST /rotate-key
98
- # Body: { key: "<current-insider-key>" }
99
- ```
78
+ | Method | Path | Description |
79
+ |--------|------|-------------|
80
+ | `GET` | `/api/auth/status` | Check authentication status and mode |
100
81
 
101
82
  ### Event Gateway
102
83
 
103
- ```bash
104
- # Send a webhook
105
- POST /event?key=<webhook-key>
106
- Content-Type: application/json
107
- Body: { "type": "page.content_updated", "data": { "page_id": "abc123" } }
108
- # Returns: { matched: "notion-page-update" } or { matched: null }
109
- ```
84
+ | Method | Path | Description |
85
+ |--------|------|-------------|
86
+ | `POST` | `/event` | Send a webhook (matched against configured schemas) |
110
87
 
111
- ### Health
88
+ ### Search (requires watcher integration)
112
89
 
113
- ```bash
114
- GET /health
115
- # Returns: 200 OK (no auth required)
116
- ```
90
+ | Method | Path | Description |
91
+ |--------|------|-------------|
92
+ | `POST` | `/api/search` | Semantic search (proxied to jeeves-watcher) |
93
+ | `GET` | `/api/search/facets` | Get filter facets for search UI (cached) |
117
94
 
118
95
  ## Converting Windows Paths to URLs
119
96
 
120
- Jeeves Server maps Windows filesystem paths to URL paths:
121
-
122
97
  ```
123
- D:\docs\design.md → /d/docs/design.md
124
- E:\projects\foo → /e/projects/foo
98
+ D:\\docs\\design.md → /d/docs/design.md
99
+ E:\\projects\\foo → /e/projects/foo
125
100
  ```
126
101
 
127
102
  **Conversion formula:**
128
103
  1. Replace backslashes with forward slashes
129
104
  2. Replace the drive letter + colon with lowercase letter
130
- 3. Prepend the route prefix (`/path/` for legacy, `/browse/` for SPA, `/api/file/` for API)
105
+ 3. Prepend the route prefix (`/browse/` for SPA, `/api/file/` for API, `/path/` for legacy)
131
106
 
132
107
  ```javascript
133
- function winPathToUrl(winPath, prefix = '/path/') {
134
- const urlPath = winPath
135
- .replace(/\\/g, '/')
136
- .replace(/^([A-Z]):/, (_, d) => d.toLowerCase());
137
- return `${prefix}${urlPath}`;
138
- }
139
-
140
- // D:\docs\design.md → /path/d/docs/design.md
141
- // D:\docs\design.md → /browse/d/docs/design.md
142
- // D:\docs\design.md → /api/file/d/docs/design.md
143
- ```
144
-
145
- ```powershell
146
- # PowerShell equivalent
147
- function Convert-ToJeevesUrl {
148
- param([string]$Path, [string]$Prefix = '/path/')
149
- $urlPath = $Path -replace '\\','/' -replace '^([A-Z]):',{ $_.Groups[1].Value.ToLower() }
150
- return "${Prefix}${urlPath}"
108
+ function winPathToUrl(winPath, prefix = '/browse/') {
109
+ return prefix + winPath.replace(/\\\\/g, '/').replace(/^([A-Z]):/, (_, d) => d.toLowerCase());
151
110
  }
152
111
  ```
153
112
 
@@ -157,7 +116,7 @@ function Convert-ToJeevesUrl {
157
116
 
158
117
  ```javascript
159
118
  const insiderKey = computeInsiderKey(seed);
160
- const url = `https://jeeves.example.com/browse/d/docs/design.md?key=${insiderKey}`;
119
+ const url = \`https://jeeves.example.com/browse/d/docs/design.md?key=\${insiderKey}\`;
161
120
  ```
162
121
 
163
122
  ### Outsider links (path-scoped)
@@ -169,68 +128,16 @@ function outsiderKey(seed, path) {
169
128
  const normalized = path.toLowerCase().replace(/^\/+|\/+$/g, '');
170
129
  return crypto.createHmac('sha256', seed).update(normalized).digest('hex').substring(0, 32);
171
130
  }
172
-
173
- function outsiderKeyWithExpiry(seed, path, expiryMs) {
174
- const normalized = path.toLowerCase().replace(/^\/+|\/+$/g, '');
175
- const data = `${normalized}|${expiryMs}`;
176
- return crypto.createHmac('sha256', seed).update(data).digest('hex').substring(0, 32);
177
- }
178
-
179
- // Non-expiring outsider link
180
- const key = outsiderKey(seed, 'd/docs/design.md');
181
- const url = `https://jeeves.example.com/browse/d/docs/design.md?key=${key}`;
182
-
183
- // Expiring outsider link (1 week)
184
- const expiry = Date.now() + 7 * 24 * 60 * 60 * 1000;
185
- const key = outsiderKeyWithExpiry(seed, 'd/docs/design.md', expiry);
186
- const url = `https://jeeves.example.com/browse/d/docs/design.md?key=${key}&exp=${expiry}`;
187
131
  ```
188
132
 
189
- ### Directory links
190
-
191
- Outsider keys for directories grant access to all descendants:
192
-
193
- ```javascript
194
- // Share an entire directory
195
- const key = outsiderKey(seed, 'd/projects/client-x');
196
- const url = `https://jeeves.example.com/browse/d/projects/client-x?key=${key}`;
197
- // Grants access to all files under D:\projects\client-x\
198
- ```
133
+ See the [Sharing](sharing.md) guide for details on expiring links and directory sharing.
199
134
 
200
135
  ## For AI Assistants
201
136
 
202
- If you're an AI assistant working with Jeeves Server, here's what you need to know:
203
-
204
- ### Generating links to share with humans
205
-
206
- When your human asks you to share a document:
207
-
208
- 1. **Convert the Windows path** to a URL path (see above)
209
- 2. **Use the insider key** for team members, or generate an outsider key for external recipients
210
- 3. **Choose the right route**: `/browse/` for browser viewing, `/path/` with `?export=pdf` for direct PDF download
211
-
212
- ### Authoring documents
213
-
214
- Write Markdown files to the server's filesystem. Jeeves Server will render them beautifully. You can:
215
- - Embed Mermaid diagrams (rendered inline)
216
- - Embed SVG files (rendered with pan/zoom)
217
- - Use code blocks with language hints (syntax highlighted)
218
- - Reference other local files with relative paths
219
-
220
- ### Checking server status
221
-
222
- ```bash
223
- curl -s http://localhost:1934/health
224
- ```
225
-
226
- ### Triggering webhooks
227
-
228
- If you need to trigger an action via the event gateway:
229
-
230
- ```bash
231
- curl -X POST "http://localhost:1934/event?key=<webhook-key>" \
232
- -H "Content-Type: application/json" \
233
- -d '{"action": "rebuild", "target": "docs"}'
234
- ```
137
+ If you're an AI assistant working with Jeeves Server:
235
138
 
236
- Match this against a configured event schema to dispatch your handler.
139
+ 1. **Use the OpenClaw plugin** if available — it provides `server_status`, `server_browse`, `server_link_info`, `server_share`, `server_export`, and `server_event_status` tools
140
+ 2. **Convert Windows paths** to URL paths using the formula above
141
+ 3. **Use `/api/status`** for health checks (no auth required)
142
+ 4. **Prefer `/browse/` routes** for links you share with humans (renders the SPA)
143
+ 5. **Use `/api/export/` routes** for direct PDF/DOCX downloads