@observa/sdk 2.4.0 → 2.4.5

package/src/http/httpClient.ts

@@ -1,284 +0,0 @@
-import { AuthError, NetworkError, TimeoutError, mapHttpError } from './errors'
-
-/**
- * Authentication mode per request.
- */
-export type AuthMode = 'apiKey' | 'none'
-/**
- * Supported HTTP methods.
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
-/**
- * Serializable query parameters.
- */
-export type QueryParams = Record<string, string | number | boolean | undefined>
-
-/**
- * Retry policy for transient errors.
- */
-export type RetryPolicy = {
-    /**
-     * Number of additional retries.
-     */
-    retries: number
-    /**
-     * Computes the delay between retries.
-     */
-    retryDelayMs?: (attempt: number, response?: Response, error?: unknown) => number
-    /**
-     * Determines whether a response or error should be retried.
-     */
-    retryOn?: (response?: Response, error?: unknown) => boolean
-}
-
-/**
- * Base HTTP client configuration.
- */
-export type HttpClientOptions = {
-    /**
-     * Backend base URL.
-     */
-    baseUrl: string
-    /**
-     * API key used for SDK authentication.
-     */
-    apiKey?: string
-    /**
-     * Request timeout in milliseconds.
-     */
-    timeoutMs?: number
-    /**
-     * Global headers.
-     */
-    headers?: Record<string, string>
-    /**
-     * Retry policy.
-     */
-    retry?: RetryPolicy
-}
-
-/**
- * Per-request options.
- */
-export type RequestOptions = {
-    method: HttpMethod
-    path: string
-    query?: QueryParams
-    body?: unknown
-    headers?: Record<string, string>
-    /**
-     * Defines whether the request requires an apiKey or is public.
-     */
-    auth?: AuthMode
-}
-
-/**
- * Base HTTP client for the SDK.
- */
-export class HttpClient {
-    private apiKey?: string
-    private readonly baseUrl: string
-    private readonly timeoutMs: number
-    private readonly headers: Record<string, string>
-    private readonly retry?: RetryPolicy
-    private healthCheckPromise?: Promise<unknown>
-
-    /**
-     * Creates an HTTP client with baseUrl and optional apiKey.
-     */
-    constructor(options: HttpClientOptions) {
-        this.baseUrl = options.baseUrl.replace(/\/+$/, '')
-        this.apiKey = options.apiKey
-        this.timeoutMs = options.timeoutMs ?? 5000
-        this.headers = options.headers ?? {}
-        this.retry = options.retry
-    }
-
-    /**
-     * Updates the API key at runtime.
-     */
-    setApiKey(apiKey?: string) {
-        this.apiKey = apiKey
-    }
-
-    /**
-     * Checks if an API key is configured.
-     */
-    hasApiKey(): boolean {
-        return !!this.apiKey
-    }
-
-    startHealthCheck(healthCheck: () => Promise<unknown>) {
-        if (!this.healthCheckPromise) {
-            const promise = healthCheck()
-            this.healthCheckPromise = promise
-            promise.catch(() => undefined)
-        }
-    }
-
-    /**
-     * GET request.
-     */
-    async get<T>(path: string, options?: Omit<RequestOptions, 'method' | 'path'>): Promise<T> {
-        return this.request<T>({ method: 'GET', path, ...options })
-    }
-
-    /**
-     * POST request.
-     */
-    async post<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'path' | 'body'>): Promise<T> {
-        return this.request<T>({ method: 'POST', path, body, ...options })
-    }
-
-    /**
-     * PUT request.
-     */
-    async put<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'path' | 'body'>): Promise<T> {
-        return this.request<T>({ method: 'PUT', path, body, ...options })
-    }
-
-    /**
-     * PATCH request.
-     */
-    async patch<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'path' | 'body'>): Promise<T> {
-        return this.request<T>({ method: 'PATCH', path, body, ...options })
-    }
-
-    /**
-     * DELETE request.
-     */
-    async delete<T>(path: string, options?: Omit<RequestOptions, 'method' | 'path'>): Promise<T> {
-        return this.request<T>({ method: 'DELETE', path, ...options })
-    }
-
-    /**
-     * Executes a request with retry logic.
-     */
-    async request<T>(options: RequestOptions): Promise<T> {
-        if (this.healthCheckPromise) {
-            await this.healthCheckPromise
-        }
-        const retry = this.retry ?? { retries: 0 }
-        const retryOn = retry.retryOn ?? ((response?: Response, error?: unknown) => {
-            if (response) return response.status === 429 || response.status >= 500
-            return error instanceof NetworkError || error instanceof TimeoutError || error instanceof TypeError
-        })
-        const retryDelayMs = retry.retryDelayMs ?? ((attempt: number) => Math.min(1000 * 2 ** (attempt - 1), 8000))
-        let lastError: unknown
-
-        for (let attempt = 0; attempt <= retry.retries; attempt += 1) {
-            try {
-                const { response, data } = await this.execute(options)
-                if (!response.ok) {
-                    const retryAfter = this.parseRetryAfter(response.headers.get('retry-after'))
-                    const error = mapHttpError(response.status, data, retryAfter)
-                    if (retryOn(response, error) && attempt < retry.retries) {
-                        await this.delay(retryDelayMs(attempt + 1, response, error))
-                        continue
-                    }
-                    throw error
-                }
-                return data as T
-            } catch (error) {
-                lastError = error
-                if (retryOn(undefined, error) && attempt < retry.retries) {
-                    await this.delay(retryDelayMs(attempt + 1, undefined, error))
-                    continue
-                }
-                throw error
-            }
-        }
-
-        throw lastError
-    }
-
-    /**
-     * Executes a request without retry and returns response + data.
-     */
-    private async execute(options: RequestOptions): Promise<{ response: Response; data: unknown }> {
-        const url = this.buildUrl(options.path, options.query)
-        const headers: Record<string, string> = { ...this.headers, ...options.headers }
-        if (options.body !== undefined) headers['content-type'] = 'application/json'
-        const authMode = options.auth ?? 'none'
-        if (authMode === 'apiKey') {
-            if (!this.apiKey) throw new AuthError('API key is required')
-            headers['x-api-key'] = this.apiKey
-        }
-
-        const controller = new AbortController()
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs)
-
-        try {
-            const response = await fetch(url, {
-                method: options.method,
-                headers,
-                body: options.body === undefined ? undefined : JSON.stringify(options.body),
-                signal: controller.signal,
-            })
-            const data = await this.readBody(response)
-            return { response, data }
-        } catch (error: any) {
-            if (error?.name === 'AbortError') {
-                throw new TimeoutError('Request timeout')
-            }
-            if (error instanceof NetworkError || error instanceof TimeoutError) throw error
-            if (error instanceof Error) {
-                if (error instanceof AuthError) throw error
-            }
-            if (error instanceof Error && 'status' in error) throw error
-            throw new NetworkError('Network error', { details: error })
-        } finally {
-            clearTimeout(timer)
-        }
-    }
-
-    /**
-     * Builds the final URL with query params.
-     */
-    private buildUrl(path: string, query?: QueryParams): string {
-        const base = this.baseUrl
-        const fullPath = path.startsWith('http') ? path : `${base}${path.startsWith('/') ? '' : '/'}${path}`
-        if (!query) return fullPath
-        const params = new URLSearchParams()
-        for (const [key, value] of Object.entries(query)) {
-            if (value === undefined) continue
-            params.set(key, String(value))
-        }
-        const suffix = params.toString()
-        return suffix ? `${fullPath}?${suffix}` : fullPath
-    }
-
-    /**
-     * Parses the body as JSON when possible.
-     */
-    private async readBody(response: Response): Promise<unknown> {
-        if (response.status === 204) return undefined
-        const text = await response.text()
-        if (!text) return undefined
-        try {
-            return JSON.parse(text)
-        } catch {
-            return text
-        }
-    }
-
-    private parseRetryAfter(value: string | null): number | undefined {
-        if (!value) return undefined
-        const seconds = Number(value)
-        if (!Number.isNaN(seconds) && Number.isFinite(seconds)) {
-            return Math.max(0, seconds)
-        }
-        const parsedDate = Date.parse(value)
-        if (Number.isNaN(parsedDate)) return undefined
-        const diffMs = parsedDate - Date.now()
-        if (diffMs <= 0) return 0
-        return Math.ceil(diffMs / 1000)
-    }
-
-    /**
-     * Simple delay for retries.
-     */
-    private async delay(ms: number): Promise<void> {
-        await new Promise(resolve => setTimeout(resolve, ms))
-    }
-}

package/src/index.ts

@@ -1,68 +0,0 @@
-/**
- * Main SDK.
- */
-export { ObservaSDK } from './sdk'
-/**
- * SDK options.
- */
-export type { ObservaSDKOptions } from './sdk'
-
-/**
- * Base HTTP client.
- */
-export { HttpClient } from './http/httpClient'
-/**
- * HTTP types.
- */
-export type { HttpClientOptions, RequestOptions, RetryPolicy, AuthMode } from './http/httpClient'
-
-/**
- * Typed SDK errors.
- */
-export {
-  SdkError,
-  ValidationError,
-  AuthError,
-  ForbiddenError,
-  NotFoundError,
-  ConflictError,
-  RateLimitError,
-  ServerError,
-  NetworkError,
-  TimeoutError,
-} from './http/errors'
-
-/**
- * Domain APIs.
- */
-export { UptimeApi } from './apis/uptimeApi'
-export { IngestApi } from './apis/ingestApi'
-export type { IngestNormalizationOptions } from './apis/ingestApi'
-
-/**
- * Uptime types.
- */
-export type { UptimeEvent, UptimeStatus, UptimeHeartbeatInput, UptimeSummary } from './domain/uptime'
-/**
- * Ingestion types.
- */
-export type {
-  IngestEvent,
-  IngestEventContext,
-  IngestException,
-  IngestLevel,
-  IngestRequest,
-  IngestResponse,
-  RequestContext,
-  Stacktrace,
-  StacktraceFrame,
-} from './domain/ingest'
-export type {
-  ProcessContext,
-  ProcessContextDynamic,
-  ProcessContextDynamicOptions,
-  ProcessContextOptions,
-  ProcessContextStatic,
-  ProcessContextStaticOptions,
-} from './utils/processContext'
-export { getProcessContext, getProcessContextDynamic, getProcessContextStatic } from './utils/processContext'

package/src/sdk.ts

@@ -1,107 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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`)
-    }
-}