@vaultcompass/vault-guard-telemetry 1.0.1 → 1.0.3
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 +97 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# @vaultcompass/vault-guard-telemetry
|
|
2
|
+
|
|
3
|
+
Opt-in, **local-only** store for [Vault Guard](https://github.com/vaultcompasshq/vault-guard). Tracks Anthropic API token cost (via the local `vault-guard proxy`) and session events such as `secret_blocked`, `revert`, and `accept` in `~/.vault-guard/usage.sqlite`. Nothing is sent to Vault & Compass servers, and Cursor/Copilot built-in model usage is not captured.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @vaultcompass/vault-guard-telemetry
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires **Node.js 22+** and native `better-sqlite3` bindings (rebuilt automatically on `npm install`).
|
|
12
|
+
|
|
13
|
+
## Quickstart
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { TelemetryStore } from '@vaultcompass/vault-guard-telemetry';
|
|
17
|
+
|
|
18
|
+
const store = new TelemetryStore();
|
|
19
|
+
|
|
20
|
+
// Record Anthropic API usage (e.g. from a local proxy)
|
|
21
|
+
store.recordUsage({
|
|
22
|
+
model: 'claude-sonnet-4-20250514',
|
|
23
|
+
inputTokens: 1200,
|
|
24
|
+
outputTokens: 340,
|
|
25
|
+
estCostUsd: 0.0042,
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
// Record a session event (e.g. secret blocked in editor)
|
|
29
|
+
store.recordSession({
|
|
30
|
+
eventType: 'secret_blocked',
|
|
31
|
+
extra: { pattern: 'anthropic' },
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
// Statusline payload for editor integrations
|
|
35
|
+
const status = store.getStatuslinePayload();
|
|
36
|
+
// { secrets_today, tokens_today_input, tokens_today_output, est_cost_usd, model }
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Graceful degradation
|
|
40
|
+
|
|
41
|
+
If `better-sqlite3` bindings are missing (e.g. install with `--ignore-scripts`), catch `TelemetryUnavailableError` and skip telemetry features:
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
import {
|
|
45
|
+
TelemetryStore,
|
|
46
|
+
TelemetryUnavailableError,
|
|
47
|
+
} from '@vaultcompass/vault-guard-telemetry';
|
|
48
|
+
|
|
49
|
+
try {
|
|
50
|
+
const store = new TelemetryStore();
|
|
51
|
+
console.log(store.getStatuslinePayload());
|
|
52
|
+
} catch (err) {
|
|
53
|
+
if (err instanceof TelemetryUnavailableError) {
|
|
54
|
+
// Telemetry optional; continue without it
|
|
55
|
+
} else {
|
|
56
|
+
throw err;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## CLI usage (recommended for end users)
|
|
62
|
+
|
|
63
|
+
Most users interact with telemetry through the main CLI, not this package directly:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm install -g @vaultcompass/vault-guard
|
|
67
|
+
|
|
68
|
+
vault-guard proxy --listen 127.0.0.1:8765 # Anthropic proxy + usage logging
|
|
69
|
+
vault-guard statusline --json
|
|
70
|
+
vault-guard data status
|
|
71
|
+
vault-guard data export -o usage.json
|
|
72
|
+
vault-guard data reset --yes
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Set `ANTHROPIC_BASE_URL=http://127.0.0.1:8765` to route a client through the proxy.
|
|
76
|
+
|
|
77
|
+
## Privacy
|
|
78
|
+
|
|
79
|
+
All data stays on your machine under `~/.vault-guard/`. See [docs/PRIVACY.md](https://github.com/vaultcompasshq/vault-guard/blob/main/docs/PRIVACY.md) for schema, retention, and opt-out steps.
|
|
80
|
+
|
|
81
|
+
## Main exports
|
|
82
|
+
|
|
83
|
+
| Export | Description |
|
|
84
|
+
|--------|-------------|
|
|
85
|
+
| `TelemetryStore` | SQLite-backed usage and session store |
|
|
86
|
+
| `TelemetryUnavailableError` | Missing/incompatible native bindings |
|
|
87
|
+
| `getDefaultDbPath` | Default `~/.vault-guard/usage.sqlite` path |
|
|
88
|
+
| `getTelemetryRetentionDays` | Configurable retention window |
|
|
89
|
+
|
|
90
|
+
## Documentation
|
|
91
|
+
|
|
92
|
+
- [GitHub repository](https://github.com/vaultcompasshq/vault-guard)
|
|
93
|
+
- [Privacy policy](https://github.com/vaultcompasshq/vault-guard/blob/main/docs/PRIVACY.md)
|
|
94
|
+
|
|
95
|
+
## License
|
|
96
|
+
|
|
97
|
+
MIT. [Vault & Compass LLC](https://vaultcompass.io)
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vaultcompass/vault-guard-telemetry",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.0.3",
|
|
4
|
+
"description": "Local-only Anthropic token cost and session tracking via the Vault Guard proxy. No cloud.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
7
|
"files": [
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"license": "MIT",
|
|
24
24
|
"dependencies": {
|
|
25
25
|
"better-sqlite3": "^12.9.0",
|
|
26
|
-
"@vaultcompass/vault-guard-core": "1.0.
|
|
26
|
+
"@vaultcompass/vault-guard-core": "1.0.3"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@types/better-sqlite3": "^7.6.12",
|