@observa/sdk 2.4.0 → 2.4.5

package/src/apis/ingestApi.ts

@@ -1,199 +0,0 @@
-import { randomUUID } from 'crypto'
-import type { IngestEvent, IngestRequest, IngestResponse, StacktraceFrame } from '../domain/ingest'
-import { ValidationError } from '../http/errors'
-import { getProcessContextDynamic, getProcessContextStatic } from '../utils/processContext'
-import { ensureDefined, ensureNonEmpty } from '../utils/validate'
-import type { HttpClient } from '../http/httpClient'
-
-export type IngestNormalizationOptions = {
-    schemaVersion?: number
-    includeContext?: boolean
-    includeSystemContext?: boolean
-    includeRuntimeContext?: boolean
-    maxEventBytes?: number
-    maxFrames?: number
-    maxMessageLength?: number
-    maxExceptionValueLength?: number
-}
-
-const DEFAULT_NORMALIZATION: Required<IngestNormalizationOptions> = {
-    schemaVersion: 1,
-    includeContext: true,
-    includeSystemContext: true,
-    includeRuntimeContext: true,
-    maxEventBytes: 64 * 1024,
-    maxFrames: 60,
-    maxMessageLength: 4000,
-    maxExceptionValueLength: 4000,
-}
-
-/**
- * Event ingestion API.
- */
-export class IngestApi {
-    /**
-     * Creates the ingestion client with an optional default DSN and PublicKey.
-     */
-    constructor(
-        private readonly http: HttpClient,
-        private readonly defaultDsnKey?: string,
-        private readonly normalization?: IngestNormalizationOptions,
-        private readonly defaultPublicKey?: string
-    ) { }
-
-    /**
-     * Sends an event to the ingestion backend.
-     */
-    async event(input: IngestRequest): Promise<IngestResponse> {
-        ensureDefined(input, 'input')
-        const dsnKey = input.dsnKey ?? this.defaultDsnKey
-        const publicKey = input.publicKey ?? this.defaultPublicKey
-
-        ensureDefined(dsnKey, 'dsnKey')
-        ensureNonEmpty(dsnKey, 'dsnKey')
-        ensureDefined(input.event, 'event')
-
-        if (!this.http.hasApiKey() && !publicKey) {
-            throw new ValidationError('publicKey is required when apiKey is not provided')
-        }
-
-        if (input.idempotencyKey && input.idempotencyKey.length > 128) {
-            throw new ValidationError('idempotencyKey must be at most 128 characters')
-        }
-        const headers: Record<string, string> = {}
-        if (input.idempotencyKey) headers['x-idempotency-key'] = input.idempotencyKey
-        if (input.sdkVersion) headers['x-sdk-version'] = input.sdkVersion
-        const { idempotencyKey, sdkVersion, event, ...body } = input
-        const normalizedEvent = normalizeEvent(event, this.normalization)
-        
-        const authMode = this.http.hasApiKey() ? 'apiKey' : 'none'
-        return this.http.post<IngestResponse>('/ingest/events', { ...body, dsnKey, publicKey, event: normalizedEvent }, { auth: authMode, headers })
-    }
-
-    async health(dsnKey?: string, publicKey?: string): Promise<{ ok: boolean }> {
-        const resolvedDsnKey = dsnKey ?? this.defaultDsnKey
-        const resolvedPublicKey = publicKey ?? this.defaultPublicKey
-
-        ensureDefined(resolvedDsnKey, 'dsnKey')
-        ensureNonEmpty(resolvedDsnKey, 'dsnKey')
-        
-        const authMode = this.http.hasApiKey() ? 'apiKey' : 'none'
-        return this.http.post<{ ok: boolean }>('/ingest/health', { dsnKey: resolvedDsnKey, publicKey: resolvedPublicKey }, { auth: authMode })
-    }
-}
-
-function normalizeEvent(event: IngestEvent, options?: IngestNormalizationOptions): IngestEvent {
-    const config = { ...DEFAULT_NORMALIZATION, ...options }
-    const normalizedTimestamp = normalizeTimestamp(event.timestamp)
-    const normalizedLevel = event.level ? event.level.toLowerCase() : undefined
-    const normalizedMessage = event.message ? truncate(event.message, config.maxMessageLength) : undefined
-    const normalizedException = normalizeException(event.exception, config)
-    if (!normalizedMessage && !normalizedException) {
-        throw new ValidationError('event message or exception is required')
-    }
-    const normalizedContext = normalizeContext(event.context, config)
-    const normalizedEvent: IngestEvent = {
-        ...event,
-        event_id: event.event_id ?? randomUUID(),
-        timestamp: normalizedTimestamp,
-        schema_version: event.schema_version ?? config.schemaVersion,
-        level: normalizedLevel as IngestEvent['level'],
-        message: normalizedMessage,
-        exception: normalizedException,
-        context: normalizedContext,
-    }
-    return enforceSizeLimit(normalizedEvent, config)
-}
-
-function normalizeTimestamp(timestamp?: string) {
-    if (!timestamp) return new Date().toISOString()
-    const parsed = new Date(timestamp)
-    if (Number.isNaN(parsed.getTime())) {
-        throw new ValidationError('timestamp must be a valid ISO date')
-    }
-    return parsed.toISOString()
-}
-
-function normalizeException(exception: IngestEvent['exception'], config: Required<IngestNormalizationOptions>) {
-    if (!exception) return undefined
-    if (!exception.type || !exception.value) {
-        throw new ValidationError('exception.type and exception.value are required')
-    }
-    return {
-        ...exception,
-        value: truncate(exception.value, config.maxExceptionValueLength),
-        stacktrace: normalizeStacktrace(exception.stacktrace, config.maxFrames),
-    }
-}
-
-function normalizeStacktrace(stacktrace: { frames?: StacktraceFrame[] } | undefined, maxFrames: number) {
-    if (!stacktrace || !Array.isArray(stacktrace.frames)) return undefined
-    const frames = stacktrace.frames
-    const normalizedFrames = frames.slice(0, maxFrames).map((frame) => {
-        const filename = typeof frame?.filename === 'string' ? frame.filename : undefined
-        const functionName = typeof frame?.function === 'string' ? frame.function : undefined
-        const lineno = typeof frame?.lineno === 'number' ? frame.lineno : undefined
-        const colno = typeof frame?.colno === 'number' ? frame.colno : undefined
-        const inferredInApp = filename ? !filename.includes('node_modules') : false
-        return {
-            filename,
-            function: functionName,
-            lineno,
-            colno,
-            in_app: typeof frame?.in_app === 'boolean' ? frame.in_app : inferredInApp,
-        }
-    })
-    return { frames: normalizedFrames }
-}
-
-function normalizeContext(context: IngestEvent['context'] | undefined, config: Required<IngestNormalizationOptions>) {
-    if (!config.includeContext) return context
-    const systemContext = config.includeSystemContext ? getProcessContextDynamic() : undefined
-    const runtimeContext = config.includeRuntimeContext ? getProcessContextStatic({ includeVersions: false }) : undefined
-    const mergedContext = {
-        ...context,
-        system: context?.system ?? systemContext,
-        runtime: context?.runtime ?? runtimeContext,
-    }
-    return mergedContext
-}
-
-function enforceSizeLimit(event: IngestEvent, config: Required<IngestNormalizationOptions>) {
-    let normalized = event
-    if (getSize(normalized) <= config.maxEventBytes) return normalized
-    if (normalized.extra) {
-        normalized = { ...normalized, extra: undefined }
-    }
-    if (getSize(normalized) <= config.maxEventBytes) return normalized
-    if (normalized.tags) {
-        normalized = { ...normalized, tags: undefined }
-    }
-    if (getSize(normalized) <= config.maxEventBytes) return normalized
-    if (normalized.exception?.stacktrace) {
-        normalized = {
-            ...normalized,
-            exception: { ...normalized.exception, stacktrace: undefined },
-        }
-    }
-    if (getSize(normalized) <= config.maxEventBytes) return normalized
-    if (normalized.message) {
-        normalized = { ...normalized, message: truncate(normalized.message, config.maxMessageLength) }
-    }
-    if (normalized.exception?.value) {
-        normalized = {
-            ...normalized,
-            exception: { ...normalized.exception, value: truncate(normalized.exception.value, config.maxExceptionValueLength) },
-        }
-    }
-    if (getSize(normalized) <= config.maxEventBytes) return normalized
-    throw new ValidationError('event payload exceeds size limit')
-}
-
-function getSize(value: unknown) {
-    return Buffer.byteLength(JSON.stringify(value), 'utf8')
-}
-
-function truncate(value: string, maxLength: number) {
-    if (value.length <= maxLength) return value
-    return value.slice(0, maxLength)
-}

package/src/apis/uptimeApi.ts

@@ -1,58 +0,0 @@
-import type { UptimeEvent, UptimeHeartbeatInput, UptimeSummary } from '../domain/uptime'
-import { ensureDefined, ensureNonEmpty } from '../utils/validate'
-import type { HttpClient } from '../http/httpClient'
-
-/**
- * Uptime API for heartbeats and public reads.
- */
-export class UptimeApi {
-    /**
-     * Creates the uptime client with an optional default DSN.
-     */
-    constructor(private readonly http: HttpClient, private readonly defaultDsnKey?: string) { }
-
-    /**
-     * Records an uptime heartbeat.
-     */
-    async recordHeartbeat(input: UptimeHeartbeatInput): Promise<UptimeEvent> {
-        ensureDefined(input, 'input')
-        const dsnKey = input.dsnKey ?? this.defaultDsnKey
-        ensureDefined(dsnKey, 'dsnKey')
-        ensureNonEmpty(dsnKey, 'dsnKey')
-        ensureNonEmpty(input.status, 'status')
-        return this.http.post<UptimeEvent>('/uptime/heartbeats', { ...input, dsnKey }, { auth: 'apiKey' })
-    }
-
-    /**
-     * Lists a project's daily uptime history.
-     */
-    async history(projectId: string, date: string): Promise<UptimeEvent[]> {
-        ensureNonEmpty(projectId, 'projectId')
-        ensureNonEmpty(date, 'date')
-        return this.http.get<UptimeEvent[]>(`/projects/${encodeURIComponent(projectId)}/uptime/history`, {
-            query: { date },
-            auth: 'none',
-        })
-    }
-
-    /**
-     * Gets the latest uptime event for a project.
-     */
-    async latest(projectId: string): Promise<UptimeEvent | null> {
-        ensureNonEmpty(projectId, 'projectId')
-        return this.http.get<UptimeEvent | null>(`/projects/${encodeURIComponent(projectId)}/uptime/latest`, {
-            auth: 'none',
-        })
-    }
-
-    /**
-     * Summarizes daily uptime.
-     */
-    async summary(projectId: string, days?: number, delayThresholdMinutes?: number): Promise<UptimeSummary[]> {
-        ensureNonEmpty(projectId, 'projectId')
-        return this.http.get<UptimeSummary[]>(`/projects/${encodeURIComponent(projectId)}/uptime/summary`, {
-            query: { days, delayThresholdMinutes },
-            auth: 'none',
-        })
-    }
-}

package/src/domain/ingest.ts

@@ -1,93 +0,0 @@
-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
-    /**
-     * Public key for frontend/mobile projects.
-     */
-    publicKey?: 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

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

@@ -1,88 +0,0 @@
-/**
- * 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)
-}