heimdall-sdk 0.2.0 → 0.2.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.
- package/README.md +122 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# heimdall-sdk
|
|
2
|
+
|
|
3
|
+
**Zero-config API logger for React (and any JS framework).**
|
|
4
|
+
|
|
5
|
+
The Heimdall SDK automatically intercepts every `fetch` and `XMLHttpRequest` call in your frontend and sends the logs to a [Heimdall](https://github.com/alessandroamormino/heimdall) server, where you can browse them in a dashboard.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Requirements
|
|
10
|
+
|
|
11
|
+
A running Heimdall server. The easiest way is Docker:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
docker run -d \
|
|
15
|
+
--name heimdall \
|
|
16
|
+
-p 3333:3333 \
|
|
17
|
+
-v heimdall_data:/data \
|
|
18
|
+
ghcr.io/alessandroamormino/heimdall:latest
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
See the [full server setup guide](https://github.com/alessandroamormino/heimdall).
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install heimdall-sdk
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Usage
|
|
34
|
+
|
|
35
|
+
### React
|
|
36
|
+
|
|
37
|
+
```tsx
|
|
38
|
+
// main.tsx or App.tsx
|
|
39
|
+
import { HeimdallProvider } from 'heimdall-sdk'
|
|
40
|
+
|
|
41
|
+
export default function App() {
|
|
42
|
+
return (
|
|
43
|
+
<HeimdallProvider collectorUrl="http://localhost:3333">
|
|
44
|
+
<YourApp />
|
|
45
|
+
</HeimdallProvider>
|
|
46
|
+
)
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
That's it. Every `fetch` and `XHR` call is now logged automatically.
|
|
51
|
+
|
|
52
|
+
### Next.js
|
|
53
|
+
|
|
54
|
+
```tsx
|
|
55
|
+
// app/layout.tsx
|
|
56
|
+
import { HeimdallProvider } from 'heimdall-sdk'
|
|
57
|
+
|
|
58
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
59
|
+
return (
|
|
60
|
+
<html>
|
|
61
|
+
<body>
|
|
62
|
+
<HeimdallProvider collectorUrl="http://localhost:3333">
|
|
63
|
+
{children}
|
|
64
|
+
</HeimdallProvider>
|
|
65
|
+
</body>
|
|
66
|
+
</html>
|
|
67
|
+
)
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
> Add `'use client'` at the top if Next.js requires it.
|
|
72
|
+
|
|
73
|
+
### Vue / Svelte / Vanilla JS
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { patchFetch } from 'heimdall-sdk'
|
|
77
|
+
|
|
78
|
+
patchFetch({
|
|
79
|
+
collectorUrl: 'http://localhost:3333',
|
|
80
|
+
project: 'my-app',
|
|
81
|
+
})
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Options
|
|
87
|
+
|
|
88
|
+
| Prop | Type | Default | Description |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| `collectorUrl` | `string` | — | **Required.** URL of the Heimdall server |
|
|
91
|
+
| `project` | `string` | `"default"` | Label to group logs by app |
|
|
92
|
+
| `ignore` | `(string \| RegExp)[]` | `[]` | URLs to skip (matched by substring or regex) |
|
|
93
|
+
| `enabled` | `boolean` | `true` | Set to `false` to disable interception |
|
|
94
|
+
|
|
95
|
+
```tsx
|
|
96
|
+
<HeimdallProvider
|
|
97
|
+
collectorUrl="http://localhost:3333"
|
|
98
|
+
project="my-app"
|
|
99
|
+
ignore={['/health', /^\/internal/]}
|
|
100
|
+
enabled={process.env.NODE_ENV !== 'production'}
|
|
101
|
+
>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Secret detection
|
|
107
|
+
|
|
108
|
+
The SDK automatically scans every request for exposed secrets **before** sending the log. If a token or credential is found, its value is replaced with `[REDACTED]` and a warning is recorded.
|
|
109
|
+
|
|
110
|
+
| Location | Examples |
|
|
111
|
+
|---|---|
|
|
112
|
+
| **URL query parameters** | `access_token`, `api_key`, `token`, `secret`, `password`, … |
|
|
113
|
+
| **Request headers** | `Authorization`, `x-api-key`, `x-auth-token`, `Cookie`, … |
|
|
114
|
+
| **Token-shaped values** | JWT (`eyJ…`), Mapbox (`sk.`/`pk.`), long hex/base64 strings |
|
|
115
|
+
|
|
116
|
+
The real token never reaches the server or the database — redaction happens entirely in the browser.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## License
|
|
121
|
+
|
|
122
|
+
MIT — © Alessandro Amormino
|