@observa/sdk 1.0.0 → 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 +114 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,20 +1,122 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Observa SDK for Node.js
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Official SDK for sending ingest events and uptime heartbeats to Observa.
|
|
4
|
+
|
|
5
|
+
## Who is this for?
|
|
6
|
+
|
|
7
|
+
This SDK is intended for backend services, workers, and server-side applications.
|
|
8
|
+
It is not designed for browser usage.
|
|
9
|
+
|
|
10
|
+
## SDK Contract
|
|
11
|
+
|
|
12
|
+
This SDK is an official client for the Observa backend.
|
|
13
|
+
It targets a fixed API and does not support custom base URLs.
|
|
14
|
+
|
|
15
|
+
## Concepts
|
|
16
|
+
|
|
17
|
+
- **apiKey**: Organization-level credential used for authentication.
|
|
18
|
+
- **dsnKey**: Project-level identifier used to route events and heartbeats.
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
4
21
|
|
|
5
22
|
```bash
|
|
6
|
-
|
|
23
|
+
npm install @observa/sdk
|
|
7
24
|
```
|
|
8
25
|
|
|
9
|
-
|
|
26
|
+
## Usage
|
|
10
27
|
|
|
11
|
-
```
|
|
12
|
-
|
|
28
|
+
```ts
|
|
29
|
+
import { ObservaSDK } from '@observa/sdk'
|
|
30
|
+
|
|
31
|
+
const sdk = new ObservaSDK({
|
|
32
|
+
apiKey: 'org_api_key',
|
|
33
|
+
dsnKey: 'project_dsn',
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The SDK targets the Observa backend health endpoint for internal availability checks.
|
|
38
|
+
|
|
39
|
+
## Defaults
|
|
40
|
+
|
|
41
|
+
- Timeout: 5 seconds
|
|
42
|
+
- Retries: disabled by default
|
|
43
|
+
- `dsnKey` is required for ingest and uptime writes
|
|
44
|
+
|
|
45
|
+
## Ingest Events
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
const result = await sdk.ingest.event({
|
|
49
|
+
event: {
|
|
50
|
+
level: 'error',
|
|
51
|
+
message: 'Something went wrong',
|
|
52
|
+
payload: { requestId: 'req_123' },
|
|
53
|
+
},
|
|
54
|
+
})
|
|
55
|
+
|
|
56
|
+
console.log(result.event_id)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Required:
|
|
60
|
+
- `apiKey` is sent as `x-api-key` header
|
|
61
|
+
- `dsnKey` is sent in the body as `dsnKey`
|
|
62
|
+
|
|
63
|
+
## Uptime Heartbeats
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
const heartbeat = await sdk.uptime.recordHeartbeat({
|
|
67
|
+
status: 'up',
|
|
68
|
+
responseTimeMs: 120,
|
|
69
|
+
checkedAt: new Date().toISOString(),
|
|
70
|
+
message: 'Service healthy',
|
|
71
|
+
})
|
|
72
|
+
|
|
73
|
+
console.log(heartbeat.id)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Uptime Queries
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
const history = await sdk.uptime.history('project_id', '2026-02-08')
|
|
80
|
+
const latest = await sdk.uptime.latest('project_id')
|
|
81
|
+
const summary = await sdk.uptime.summary('project_id', 30)
|
|
13
82
|
```
|
|
14
83
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
##
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
84
|
+
These endpoints are public and do not require authentication.
|
|
85
|
+
|
|
86
|
+
## Updating Credentials
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
sdk.setApiKey('new_api_key')
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Error Handling
|
|
93
|
+
|
|
94
|
+
The SDK throws typed errors you can catch explicitly:
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import { RateLimitError, AuthError } from '@observa/sdk'
|
|
98
|
+
|
|
99
|
+
try {
|
|
100
|
+
await sdk.ingest.event({ event: { level: 'error', message: 'boom' } })
|
|
101
|
+
} catch (error) {
|
|
102
|
+
if (error instanceof RateLimitError) {
|
|
103
|
+
console.log('Retry after seconds:', error.retryAfter)
|
|
104
|
+
}
|
|
105
|
+
if (error instanceof AuthError) {
|
|
106
|
+
console.log('Authentication failed')
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Requirements
|
|
112
|
+
|
|
113
|
+
- Node.js >= 18
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT
|
|
118
|
+
|
|
119
|
+
## Links
|
|
120
|
+
|
|
121
|
+
- Documentation: ...
|
|
122
|
+
- GitHub: https://github.com/ObservaSolutions/sdk-observa
|