@observa/sdk 2.3.0 → 2.4.0

package/src/sdk.ts

@@ -0,0 +1,107 @@
+import { IngestApi, type IngestNormalizationOptions } from './apis/ingestApi'
+import { UptimeApi } from './apis/uptimeApi'
+import { HttpClient, type RetryPolicy } from './http/httpClient'
+import {
+    getProcessContext,
+    getProcessContextDynamic,
+    getProcessContextStatic,
+    type ProcessContext,
+    type ProcessContextDynamic,
+    type ProcessContextDynamicOptions,
+    type ProcessContextOptions,
+    type ProcessContextStatic,
+    type ProcessContextStaticOptions,
+} from './utils/processContext'
+
+/**
+ * SDK configuration options.
+ */
+export type ObservaSDKOptions = {
+    /**
+     * Organization API key used to authenticate SDK requests.
+     */
+    apiKey?: string
+    /**
+     * Project DSN used to identify the destination of events and heartbeats.
+     */
+    dsnKey: string
+    /**
+     * Public key for frontend/mobile projects.
+     */
+    publicKey?: string
+    baseUrl?: string
+    /**
+     * HTTP request timeout in milliseconds.
+     */
+    timeoutMs?: number
+    /**
+     * Retry policy for transient errors.
+     */
+    retry?: RetryPolicy
+    /**
+     * Additional headers sent with every request.
+     */
+    headers?: Record<string, string>
+    ingest?: IngestNormalizationOptions
+}
+
+/**
+ * Fixed backend target for the SDK.
+ */
+const DEFAULT_BASE_URL = 'https://backend-observa-production.up.railway.app/v1'
+
+/**
+ * Main SDK for error ingestion and uptime heartbeats.
+ */
+export class ObservaSDK {
+    /**
+     * Uptime API (heartbeats and public reads).
+     */
+    readonly uptime: UptimeApi
+    /**
+     * Event ingestion API.
+     */
+    readonly ingest: IngestApi
+
+    private readonly http: HttpClient
+
+    /**
+     * Creates an SDK instance with required dsnKey and either apiKey or publicKey.
+     */
+    constructor(options: ObservaSDKOptions) {
+        if (!options || (!options.apiKey && !options.publicKey) || !options.dsnKey) {
+            throw new Error('ObservaSDK requires dsnKey and either apiKey or publicKey')
+        }
+        const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
+        const normalizedBaseUrl = baseUrl.endsWith('/v1') ? baseUrl : `${baseUrl}/v1`
+        this.http = new HttpClient({
+            baseUrl: normalizedBaseUrl,
+            apiKey: options.apiKey,
+            timeoutMs: options.timeoutMs,
+            retry: options.retry,
+            headers: options.headers,
+        })
+        this.ingest = new IngestApi(this.http, options.dsnKey, options.ingest, options.publicKey)
+        this.uptime = new UptimeApi(this.http, options.dsnKey)
+        this.http.startHealthCheck(() => this.ingest.health(options.dsnKey, options.publicKey))
+    }
+
+    /**
+     * Updates the API key used by the SDK at runtime.
+     */
+    setApiKey(apiKey: string) {
+        this.http.setApiKey(apiKey)
+    }
+
+    getProcessContext(options?: ProcessContextOptions): ProcessContext {
+        return getProcessContext(options)
+    }
+
+    getProcessContextStatic(options?: ProcessContextStaticOptions): ProcessContextStatic {
+        return getProcessContextStatic(options)
+    }
+
+    getProcessContextDynamic(options?: ProcessContextDynamicOptions): ProcessContextDynamic {
+        return getProcessContextDynamic(options)
+    }
+}

package/src/utils/processContext.ts

@@ -0,0 +1,84 @@
+export type ProcessContextStatic = {
+    versions?: NodeJS.ProcessVersions
+    node?: string
+    platform?: NodeJS.Platform
+    arch?: string
+    releaseName?: string
+}
+
+export type ProcessContextDynamic = {
+    pid?: number
+    uptimeSeconds?: number
+    memory?: NodeJS.MemoryUsage
+}
+
+export type ProcessContext = ProcessContextStatic & ProcessContextDynamic
+
+export type ProcessContextOptions = {
+    includeStatic?: boolean
+    includeDynamic?: boolean
+    includeVersions?: boolean
+    includeRuntime?: boolean
+    includePid?: boolean
+    includeUptime?: boolean
+    includeMemory?: boolean
+}
+
+export type ProcessContextStaticOptions = {
+    includeVersions?: boolean
+    includeRuntime?: boolean
+}
+
+export type ProcessContextDynamicOptions = {
+    includePid?: boolean
+    includeUptime?: boolean
+    includeMemory?: boolean
+}
+
+export function getProcessContext(options?: ProcessContextOptions): ProcessContext {
+    const includeStatic = options?.includeStatic ?? true
+    const includeDynamic = options?.includeDynamic ?? true
+    const includeVersions = options?.includeVersions ?? true
+    const includeRuntime = options?.includeRuntime ?? true
+    const includePid = options?.includePid ?? true
+    const includeUptime = options?.includeUptime ?? true
+    const includeMemory = options?.includeMemory ?? true
+    const context: ProcessContext = {}
+
+    if (includeDynamic) {
+        if (includePid) context.pid = process.pid
+        if (includeUptime) context.uptimeSeconds = Math.round(process.uptime())
+        if (includeMemory) context.memory = process.memoryUsage()
+    }
+
+    if (includeStatic) {
+        if (includeVersions) context.versions = process.versions
+        if (includeRuntime) {
+            context.node = process.versions.node
+            context.platform = process.platform
+            context.arch = process.arch
+            context.releaseName = process.release?.name
+        }
+    }
+
+    return context
+}
+
+export function getProcessContextStatic(options?: ProcessContextStaticOptions): ProcessContextStatic {
+    return getProcessContext({
+        includeDynamic: false,
+        includeStatic: true,
+        includeVersions: options?.includeVersions,
+        includeRuntime: options?.includeRuntime,
+    })
+}
+
+export function getProcessContextDynamic(options?: ProcessContextDynamicOptions): ProcessContextDynamic {
+    return getProcessContext({
+        includeStatic: false,
+        includeDynamic: true,
+        includePid: options?.includePid,
+        includeUptime: options?.includeUptime,
+        includeMemory: options?.includeMemory,
+    })
+}

package/src/utils/validate.ts

@@ -0,0 +1,19 @@
+import { ValidationError } from '../http/errors'
+
+/**
+ * Ensures a string is present and non-empty.
+ */
+export function ensureNonEmpty(value: string, name: string) {
+    if (!value || value.trim().length === 0) {
+        throw new ValidationError(`${name} is required`)
+    }
+}
+
+/**
+ * Ensures a value is neither null nor undefined.
+ */
+export function ensureDefined<T>(value: T | null | undefined, name: string): asserts value is T {
+    if (value === null || value === undefined) {
+        throw new ValidationError(`${name} is required`)
+    }
+}