@observa/sdk 2.2.1 → 2.3.1

package/src/domain/ingest.ts

@@ -0,0 +1,89 @@
+import type { ProcessContextDynamic, ProcessContextStatic } from '../utils/processContext'
+
+/**
+ * Severity levels for events.
+ */
+export type IngestLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+export type StacktraceFrame = {
+    filename?: string
+    function?: string
+    lineno?: number
+    colno?: number
+    in_app?: boolean
+}
+
+export type Stacktrace = {
+    frames: StacktraceFrame[]
+}
+
+export type IngestException = {
+    type: string
+    value: string
+    stacktrace?: Stacktrace
+}
+
+export type RequestContext = {
+    requestId?: string
+    userId?: string
+    [key: string]: unknown
+}
+
+export type IngestEventContext = {
+    system?: ProcessContextDynamic
+    runtime?: ProcessContextStatic
+    request?: RequestContext
+}
+
+/**
+ * Ingestion event.
+ */
+export type IngestEvent = {
+    /**
+     * Unique event identifier.
+     */
+    event_id?: string
+    /**
+     * Event ISO timestamp.
+     */
+    timestamp?: string
+    schema_version?: number
+    /**
+     * Severity level.
+     */
+    level?: IngestLevel
+    /**
+     * Main message.
+     */
+    message?: string
+    exception?: IngestException
+    context?: IngestEventContext
+    tags?: Record<string, string>
+    extra?: Record<string, unknown>
+}
+
+/**
+ * Payload for sending an event to the backend.
+ */
+export type IngestRequest = {
+    /**
+     * Project DSN. Uses the SDK default when omitted.
+     */
+    dsnKey?: string
+    /**
+     * Event to record.
+     */
+    event: IngestEvent
+    idempotencyKey?: string
+    sdkVersion?: string
+}
+
+/**
+ * Response after sending an event.
+ */
+export type IngestResponse = {
+    /**
+     * Assigned event identifier.
+     */
+    event_id: string
+}

package/src/domain/uptime.ts

@@ -0,0 +1,86 @@
+/**
+ * Possible uptime statuses.
+ */
+export type UptimeStatus = 'up' | 'down' | 'degraded'
+
+/**
+ * Recorded uptime event.
+ */
+export type UptimeEvent = {
+    /**
+     * Event identifier.
+     */
+    id: string
+    /**
+     * Project the event belongs to.
+     */
+    projectId: string
+    /**
+     * Uptime status.
+     */
+    status: UptimeStatus
+    /**
+     * Optional message for the event.
+     */
+    message?: string
+    /**
+     * Response time in milliseconds.
+     */
+    responseTimeMs?: number
+    /**
+     * ISO timestamp of the check.
+     */
+    checkedAt?: string
+    /**
+     * ISO timestamp of backend creation.
+     */
+    createdAt?: string
+}
+
+/**
+ * Payload for sending an uptime heartbeat.
+ */
+export type UptimeHeartbeatInput = {
+    /**
+     * Project DSN. Uses the SDK default when omitted.
+     */
+    dsnKey?: string
+    /**
+     * Reported status.
+     */
+    status: UptimeStatus
+    /**
+     * Response time in milliseconds.
+     */
+    responseTimeMs?: number
+    /**
+     * ISO timestamp of the check.
+     */
+    checkedAt?: string
+    /**
+     * Optional message.
+     */
+    message?: string
+}
+
+/**
+ * Daily uptime summary.
+ */
+export type UptimeSummary = {
+    /**
+     * ISO date of the summary.
+     */
+    date: string
+    /**
+     * Hours without data.
+     */
+    missingHours?: number
+    /**
+     * Accumulated delay minutes.
+     */
+    delayMinutes?: number
+    /**
+     * Number of delayed events.
+     */
+    delayedCount?: number
+}

package/src/http/errors.ts

@@ -0,0 +1,88 @@
+/**
+ * Additional data to enrich SDK errors.
+ */
+export type ErrorDetails = {
+    status?: number
+    code?: string
+    details?: unknown
+    retryAfter?: number
+}
+
+/**
+ * Base SDK error.
+ */
+export class SdkError extends Error {
+    readonly status?: number
+    readonly code?: string
+    readonly details?: unknown
+
+    /**
+     * Creates an error with optional metadata.
+     */
+    constructor(message: string, details?: ErrorDetails) {
+        super(message)
+        this.name = new.target.name
+        this.status = details?.status
+        this.code = details?.code
+        this.details = details?.details
+    }
+}
+
+/**
+ * Input validation error.
+ */
+export class ValidationError extends SdkError { }
+/**
+ * Authentication error.
+ */
+export class AuthError extends SdkError { }
+/**
+ * Error caused by insufficient permissions.
+ */
+export class ForbiddenError extends SdkError { }
+/**
+ * Error when a resource does not exist.
+ */
+export class NotFoundError extends SdkError { }
+/**
+ * Error caused by a state conflict.
+ */
+export class ConflictError extends SdkError { }
+/**
+ * Error caused by rate limiting.
+ */
+export class RateLimitError extends SdkError {
+    readonly retryAfter?: number
+
+    constructor(message: string, details?: ErrorDetails) {
+        super(message, details)
+        this.retryAfter = details?.retryAfter
+    }
+}
+/**
+ * Server-side error.
+ */
+export class ServerError extends SdkError { }
+/**
+ * Network error.
+ */
+export class NetworkError extends SdkError { }
+/**
+ * Request timeout error.
+ */
+export class TimeoutError extends SdkError { }
+
+/**
+ * Maps HTTP status codes to typed SDK errors.
+ */
+export function mapHttpError(status: number, details?: unknown, retryAfter?: number): SdkError {
+    const info = { status, details, retryAfter }
+    if (status === 400) return new ValidationError('Invalid request', info)
+    if (status === 401) return new AuthError('Unauthorized', info)
+    if (status === 403) return new ForbiddenError('Forbidden', info)
+    if (status === 404) return new NotFoundError('Resource not found', info)
+    if (status === 409) return new ConflictError('Conflict', info)
+    if (status === 429) return new RateLimitError('Rate limit exceeded', info)
+    if (status >= 500) return new ServerError('Server error', info)
+    return new SdkError('HTTP error', info)
+}

package/src/http/httpClient.ts

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

@@ -0,0 +1,68 @@
+/**
+ * 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

@@ -0,0 +1,103 @@
+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
+    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 apiKey and dsnKey.
+     */
+    constructor(options: ObservaSDKOptions) {
+        if (!options || !options.apiKey || !options.dsnKey) {
+            throw new Error('ObservaSDK requires both apiKey and dsnKey')
+        }
+        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)
+        this.uptime = new UptimeApi(this.http, options.dsnKey)
+        this.http.startHealthCheck(() => this.ingest.health(options.dsnKey))
+    }
+
+    /**
+     * 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)
+    }
+}