npm package: @observa/sdk
Description: Observa SDK for Node.js
Latest version: 2.4.5

# Observa SDK for Node.js

Official SDK for sending ingest events and uptime heartbeats to Observa.

## Who is this for?

This SDK supports both server-side and browser usage:

- **Server-side** (Node.js workers, backend services): initialize with `apiKey` + `dsnKey` for full privileged access.
- **Browser / frontend**: initialize with `dsnKey` only — your org-level `apiKey` stays on the server.

## SDK Contract

This SDK is an official client for the Observa backend.
It targets a fixed API and does not support custom base URLs.

## Concepts

- **dsnKey**: Project-level identifier used to route events and heartbeats. Required for all write operations.
- **apiKey**: Organization-level credential for privileged server-side access. Optional — omit it for browser/public usage.

## Installation

```bash
npm install @observa/sdk
```

## Usage

### Browser / Frontend (DSN-only)

```ts
import { ObservaSDK } from '@observa/sdk'

const sdk = new ObservaSDK({ dsnKey: 'dsn_your_key' })
```

The DSN is a project-scoped key safe to use in browser environments.

### Server-side (apiKey + dsnKey)

```ts
import { ObservaSDK } from '@observa/sdk'

const sdk = new ObservaSDK({
  apiKey: 'org_api_key',
  dsnKey: 'project_dsn',
})
```

Use the `apiKey` in privileged server-side contexts (workers, backend services). Never expose your `apiKey` to the browser.

The SDK triggers a startup health check (`/health`) as a best-effort diagnostic.
This check is non-blocking: if it fails, normal SDK API calls still run with their regular timeout/retry/error behavior.

## Defaults

- Timeout: 5 seconds
- Retries: disabled by default
- `dsnKey` is required
- `apiKey` is optional (server-side only)

## Ingest Events

```ts
const result = await sdk.ingest.event({
  event: {
    level: 'error',
    message: 'Something went wrong',
    payload: { requestId: 'req_123' },
  },
})

console.log(result.event_id)
```

Required:
- `dsnKey` is sent in the body as `dsnKey` (always)
- `apiKey` is sent as `x-api-key` header (only when provided)

## Uptime Heartbeats

```ts
const heartbeat = await sdk.uptime.recordHeartbeat({
  status: 'up',
  responseTimeMs: 120,
  checkedAt: new Date().toISOString(),
  message: 'Service healthy',
})

console.log(heartbeat.id)
```

## Uptime Queries

```ts
const history = await sdk.uptime.history('project_id', '2026-02-08')
const latest = await sdk.uptime.latest('project_id')
const summary = await sdk.uptime.summary('project_id', 30)
```

These endpoints are public and do not require authentication.

## Updating Credentials

```ts
sdk.setApiKey('new_api_key')
```

## Error Handling

The SDK throws typed errors you can catch explicitly:

```ts
import { RateLimitError, AuthError } from '@observa/sdk'

try {
  await sdk.ingest.event({ event: { level: 'error', message: 'boom' } })
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Retry after seconds:', error.retryAfter)
  }
  if (error instanceof AuthError) {
    console.log('Authentication failed')
  }
}
```

## Requirements

- Node.js >= 18

## License

MIT

## Links

- Documentation: ...
- GitHub: https://github.com/ObservaSolutions/sdk-observa