@deerdesign/deertools 1.0.0 → 1.0.2
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.
- package/README.md +133 -34
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,63 +1,162 @@
|
|
|
1
|
-
# deertools
|
|
1
|
+
# @deerdesign/deertools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Official DeerTools CLI: Secure, scoped authentication and AI agent access for DeerTools product APIs.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Log in once from your computer, and grant your AI coding agent (Antigravity, Cursor, Claude Code, Lovable, CLI agents) access to DeerTools APIs **on your behalf, scoped strictly to your permissions, with zero credentials exposed in URLs**.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
### Supported Products
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
| Product Key | Name | Production URL | Description |
|
|
10
|
+
| :--- | :--- | :--- | :--- |
|
|
11
|
+
| `kosztorys` | DeerTools Kosztorys | `https://connect.deerdesign.pl/kosztorys/` | Floor plan PDF analysis, kitchen area detection, interior cost estimation |
|
|
12
|
+
| `katalog` | DeerTools Katalog | `https://connect.deerdesign.pl/katalog/` | Material catalog (Smart/Modern/High Life), category specs, products |
|
|
13
|
+
| `dostawy` | DeerTools Dostawy | `https://ship.deergroup.pl/` | Logistics, site delivery schedules, supplier shipments, tracking |
|
|
14
|
+
| `supplier` | Supplier Hub | `https://supplier.deergroup.pl/` | Supplier orders, line items, claims, delivery status |
|
|
15
|
+
| `rendermind` | RenderMind | `https://rendermind.deergroup.pl/` | pCon 3D render pipelines, AI image generation, floor plan proxies |
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
Requires **Node.js ≥ 18**. Zero runtime dependencies.
|
|
22
|
+
|
|
23
|
+
### Option 1: Run instantly with `npx` (No installation needed)
|
|
10
24
|
|
|
11
25
|
```bash
|
|
12
|
-
|
|
13
|
-
|
|
26
|
+
npx @deerdesign/deertools login rendermind
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Option 2: Install globally
|
|
14
30
|
|
|
15
|
-
|
|
31
|
+
```bash
|
|
16
32
|
npm install -g @deerdesign/deertools
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
This installs both the `deertools` binary and the convenient short alias `deer`:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
17
38
|
deertools --help
|
|
18
|
-
#
|
|
39
|
+
# or
|
|
19
40
|
deer whoami
|
|
20
41
|
```
|
|
21
42
|
|
|
22
|
-
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Authentication (OAuth 2.1 + PKCE S256)
|
|
46
|
+
|
|
47
|
+
DeerTools CLI implements the official **OAuth 2.1 Authorization Code grant with PKCE (RFC 8252, RFC 8414)**:
|
|
23
48
|
|
|
24
49
|
```bash
|
|
25
|
-
|
|
26
|
-
deertools login
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
deertools
|
|
50
|
+
# Log in to a single product with read-only access (default):
|
|
51
|
+
deertools login rendermind
|
|
52
|
+
|
|
53
|
+
# Request read + write scopes:
|
|
54
|
+
deertools login katalog --write
|
|
55
|
+
|
|
56
|
+
# Interactive login across all 5 products sequentially:
|
|
57
|
+
deertools login all
|
|
58
|
+
|
|
59
|
+
# Check current authentication status and expiration:
|
|
60
|
+
deertools whoami
|
|
61
|
+
|
|
62
|
+
# Check status in machine-readable JSON format:
|
|
63
|
+
deertools whoami --json
|
|
64
|
+
|
|
65
|
+
# Revoke local credentials:
|
|
66
|
+
deertools logout rendermind
|
|
30
67
|
```
|
|
31
68
|
|
|
32
|
-
|
|
69
|
+
### How it works under the hood
|
|
70
|
+
|
|
71
|
+
1. **RFC 8414 Discovery**: The CLI queries `/.well-known/oauth-authorization-server` on the product host to discover authorization and token endpoints.
|
|
72
|
+
2. **Loopback Server**: The CLI starts an ephemeral HTTP server on `127.0.0.1:<random-port>` and generates a cryptographically secure PKCE code verifier and S256 challenge.
|
|
73
|
+
3. **Browser Consent**: The user's default browser opens to the product's `/oauth/authorize` page. The user authenticates (SSO / Microsoft / Magic Link) and approves the requested scopes.
|
|
74
|
+
4. **Single-Use Authorization Code**: The browser redirects to the loopback server with a short-lived authorization code (60-second TTL). No keys or tokens ever appear in query strings.
|
|
75
|
+
5. **Direct Exchange**: The CLI sends a direct `POST` to the product's token endpoint (`/oauth-token`) with the code verifier.
|
|
76
|
+
6. **Local Storage**: The product issues a scoped API key (`deer_<product>_live_...`) valid for 90 days. The CLI persists it in `~/.deertools/credentials.json` with strict POSIX file permissions (`0600`).
|
|
33
77
|
|
|
34
|
-
|
|
35
|
-
2. Logujesz się w produkcie (Microsoft w Kosztorysie; kod lub link z e-maila gdzie indziej) i klikasz „Zezwól na dostęp”. Możesz obniżyć zakres do samego odczytu.
|
|
36
|
-
3. Przeglądarka wraca do CLI wyłącznie z **jednorazowym kodem** (ważnym 60 s). Klucza API nie ma w adresie.
|
|
37
|
-
4. CLI wymienia kod na klucz bezpośrednio z serwerem produktu (dowód PKCE) i zapisuje go w `~/.deertools/credentials.json` z uprawnieniami `600`.
|
|
78
|
+
---
|
|
38
79
|
|
|
39
|
-
|
|
80
|
+
## AI Agent Integration & Usage
|
|
40
81
|
|
|
41
|
-
|
|
82
|
+
### 1. Inspect Documentation & Specifications
|
|
42
83
|
|
|
43
84
|
```bash
|
|
44
|
-
|
|
45
|
-
deertools docs
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
deertools
|
|
49
|
-
|
|
50
|
-
|
|
85
|
+
# Read high-level llms.txt (public overview and authentication instructions):
|
|
86
|
+
deertools docs rendermind
|
|
87
|
+
|
|
88
|
+
# Fetch full OpenAPI 3.0 JSON specification:
|
|
89
|
+
deertools docs rendermind openapi
|
|
90
|
+
|
|
91
|
+
# List all available endpoints with required scopes:
|
|
92
|
+
deertools endpoints rendermind
|
|
51
93
|
```
|
|
52
94
|
|
|
53
|
-
|
|
95
|
+
### 2. Invoke Product APIs
|
|
54
96
|
|
|
55
|
-
|
|
97
|
+
The CLI handles authorization headers automatically, rejecting any requests to non-whitelisted hosts:
|
|
56
98
|
|
|
57
|
-
|
|
99
|
+
```bash
|
|
100
|
+
# Call GET endpoint:
|
|
101
|
+
deertools api katalog GET /api/v1/products --query category=flooring
|
|
102
|
+
|
|
103
|
+
# Call POST endpoint with JSON payload:
|
|
104
|
+
deertools api rendermind POST /api/v1/visualizations --data '{"prompt":"Modern Scandinavian kitchen"}'
|
|
105
|
+
|
|
106
|
+
# Read payload from file:
|
|
107
|
+
deertools api rendermind POST /api/v1/visualizations --data-file request.json
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 3. Specialized Helpers
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Analyze architectural floor plan PDF and calculate cost estimate (Kosztorys):
|
|
114
|
+
deertools estimate --file floorplan.pdf --kitchen 6
|
|
115
|
+
|
|
116
|
+
# Install product agent skills into ~/.gemini/config/skills:
|
|
117
|
+
deertools skill install rendermind
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Headless & CI/CD Environments
|
|
123
|
+
|
|
124
|
+
In CI pipelines or containerized agents where browser interaction is unavailable, provide API keys via environment variables:
|
|
58
125
|
|
|
59
126
|
```bash
|
|
60
|
-
|
|
127
|
+
export DEERTOOLS_KOSZTORYS_KEY="deer_kosztorys_live_..."
|
|
128
|
+
export DEERTOOLS_KATALOG_KEY="deer_katalog_live_..."
|
|
129
|
+
export DEERTOOLS_DOSTAWY_KEY="deer_dostawy_live_..."
|
|
130
|
+
export DEERTOOLS_SUPPLIER_KEY="deer_supplier_live_..."
|
|
131
|
+
export DEERTOOLS_RENDERMIND_KEY="deer_rendermind_live_..."
|
|
132
|
+
|
|
133
|
+
# Custom credentials directory:
|
|
134
|
+
export DEERTOOLS_HOME="/custom/path/.deertools"
|
|
61
135
|
```
|
|
62
136
|
|
|
63
|
-
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Exit Codes
|
|
140
|
+
|
|
141
|
+
| Code | Meaning |
|
|
142
|
+
| :--- | :--- |
|
|
143
|
+
| `0` | Success |
|
|
144
|
+
| `1` | Request or API failure (e.g. HTTP 4xx, 5xx) |
|
|
145
|
+
| `2` | Invalid CLI arguments or usage syntax |
|
|
146
|
+
| `3` | Missing or expired credentials (run `deertools login`) |
|
|
147
|
+
| `4` | Missing OpenAPI spec, documentation, or host resolution error |
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Development & Testing
|
|
152
|
+
|
|
153
|
+
DeerTools CLI is written in pure, dependency-free modern Node.js using built-in modules (`node:crypto`, `node:http`, `node:fs`, `node:test`).
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
# Run test suite:
|
|
157
|
+
npm test
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## License
|
|
161
|
+
|
|
162
|
+
MIT © Deer Design AI Team
|