@observa/sdk 2.2.1 → 2.3.1

package/dist/index.d.ts

@@ -1,36 +1,510 @@
+type ProcessContextStatic = {
+    versions?: NodeJS.ProcessVersions;
+    node?: string;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    releaseName?: string;
+};
+type ProcessContextDynamic = {
+    pid?: number;
+    uptimeSeconds?: number;
+    memory?: NodeJS.MemoryUsage;
+};
+type ProcessContext = ProcessContextStatic & ProcessContextDynamic;
+type ProcessContextOptions = {
+    includeStatic?: boolean;
+    includeDynamic?: boolean;
+    includeVersions?: boolean;
+    includeRuntime?: boolean;
+    includePid?: boolean;
+    includeUptime?: boolean;
+    includeMemory?: boolean;
+};
+type ProcessContextStaticOptions = {
+    includeVersions?: boolean;
+    includeRuntime?: boolean;
+};
+type ProcessContextDynamicOptions = {
+    includePid?: boolean;
+    includeUptime?: boolean;
+    includeMemory?: boolean;
+};
+declare function getProcessContext(options?: ProcessContextOptions): ProcessContext;
+declare function getProcessContextStatic(options?: ProcessContextStaticOptions): ProcessContextStatic;
+declare function getProcessContextDynamic(options?: ProcessContextDynamicOptions): ProcessContextDynamic;
+
 /**
- * Main SDK.
+ * Severity levels for events.
  */
-export { ObservaSDK } from './sdk';
+type IngestLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+type StacktraceFrame = {
+    filename?: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+};
+type Stacktrace = {
+    frames: StacktraceFrame[];
+};
+type IngestException = {
+    type: string;
+    value: string;
+    stacktrace?: Stacktrace;
+};
+type RequestContext = {
+    requestId?: string;
+    userId?: string;
+    [key: string]: unknown;
+};
+type IngestEventContext = {
+    system?: ProcessContextDynamic;
+    runtime?: ProcessContextStatic;
+    request?: RequestContext;
+};
 /**
- * SDK options.
+ * Ingestion event.
  */
-export type { ObservaSDKOptions } from './sdk';
+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>;
+};
 /**
- * Base HTTP client.
+ * Payload for sending an event to the backend.
  */
-export { HttpClient } from './http/httpClient';
+type IngestRequest = {
+    /**
+     * Project DSN. Uses the SDK default when omitted.
+     */
+    dsnKey?: string;
+    /**
+     * Event to record.
+     */
+    event: IngestEvent;
+    idempotencyKey?: string;
+    sdkVersion?: string;
+};
 /**
- * HTTP types.
+ * Response after sending an event.
  */
-export type { HttpClientOptions, RequestOptions, RetryPolicy, AuthMode } from './http/httpClient';
+type IngestResponse = {
+    /**
+     * Assigned event identifier.
+     */
+    event_id: string;
+};
+
 /**
- * Typed SDK errors.
+ * Authentication mode per request.
  */
-export { SdkError, ValidationError, AuthError, ForbiddenError, NotFoundError, ConflictError, RateLimitError, ServerError, NetworkError, TimeoutError, } from './http/errors';
+type AuthMode = 'apiKey' | 'none';
 /**
- * Domain APIs.
+ * Supported HTTP methods.
  */
-export { UptimeApi } from './apis/uptimeApi';
-export { IngestApi } from './apis/ingestApi';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /**
- * Uptime types.
+ * Serializable query parameters.
  */
-export type { UptimeEvent, UptimeStatus, UptimeHeartbeatInput, UptimeSummary } from './domain/uptime';
+type QueryParams = Record<string, string | number | boolean | undefined>;
 /**
- * Ingestion types.
+ * Retry policy for transient errors.
  */
-export type { IngestEvent, IngestLevel, IngestRequest, IngestResponse, IngestException, Stacktrace, StacktraceFrame } from './domain/ingest';
-export type { ProcessContext, ProcessContextDynamic, ProcessContextDynamicOptions, ProcessContextOptions, ProcessContextStatic, ProcessContextStaticOptions, } from './utils/processContext';
-export { getProcessContext, getProcessContextDynamic, getProcessContextStatic } from './utils/processContext';
-//# sourceMappingURL=index.d.ts.map
+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.
+ */
+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.
+ */
+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.
+ */
+declare class HttpClient {
+    private apiKey?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly retry?;
+    private healthCheckPromise?;
+    /**
+     * Creates an HTTP client with baseUrl and optional apiKey.
+     */
+    constructor(options: HttpClientOptions);
+    /**
+     * Updates the API key at runtime.
+     */
+    setApiKey(apiKey?: string): void;
+    startHealthCheck(healthCheck: () => Promise<unknown>): void;
+    /**
+     * GET request.
+     */
+    get<T>(path: string, options?: Omit<RequestOptions, 'method' | 'path'>): Promise<T>;
+    /**
+     * POST request.
+     */
+    post<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'path' | 'body'>): Promise<T>;
+    /**
+     * PUT request.
+     */
+    put<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'path' | 'body'>): Promise<T>;
+    /**
+     * PATCH request.
+     */
+    patch<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'path' | 'body'>): Promise<T>;
+    /**
+     * DELETE request.
+     */
+    delete<T>(path: string, options?: Omit<RequestOptions, 'method' | 'path'>): Promise<T>;
+    /**
+     * Executes a request with retry logic.
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Executes a request without retry and returns response + data.
+     */
+    private execute;
+    /**
+     * Builds the final URL with query params.
+     */
+    private buildUrl;
+    /**
+     * Parses the body as JSON when possible.
+     */
+    private readBody;
+    private parseRetryAfter;
+    /**
+     * Simple delay for retries.
+     */
+    private delay;
+}
+
+type IngestNormalizationOptions = {
+    schemaVersion?: number;
+    includeContext?: boolean;
+    includeSystemContext?: boolean;
+    includeRuntimeContext?: boolean;
+    maxEventBytes?: number;
+    maxFrames?: number;
+    maxMessageLength?: number;
+    maxExceptionValueLength?: number;
+};
+/**
+ * Event ingestion API.
+ */
+declare class IngestApi {
+    private readonly http;
+    private readonly defaultDsnKey?;
+    private readonly normalization?;
+    /**
+     * Creates the ingestion client with an optional default DSN.
+     */
+    constructor(http: HttpClient, defaultDsnKey?: string | undefined, normalization?: IngestNormalizationOptions | undefined);
+    /**
+     * Sends an event to the ingestion backend.
+     */
+    event(input: IngestRequest): Promise<IngestResponse>;
+    health(dsnKey?: string): Promise<{
+        ok: boolean;
+    }>;
+}
+
+/**
+ * Possible uptime statuses.
+ */
+type UptimeStatus = 'up' | 'down' | 'degraded';
+/**
+ * Recorded uptime event.
+ */
+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.
+ */
+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.
+ */
+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;
+};
+
+/**
+ * Uptime API for heartbeats and public reads.
+ */
+declare class UptimeApi {
+    private readonly http;
+    private readonly defaultDsnKey?;
+    /**
+     * Creates the uptime client with an optional default DSN.
+     */
+    constructor(http: HttpClient, defaultDsnKey?: string | undefined);
+    /**
+     * Records an uptime heartbeat.
+     */
+    recordHeartbeat(input: UptimeHeartbeatInput): Promise<UptimeEvent>;
+    /**
+     * Lists a project's daily uptime history.
+     */
+    history(projectId: string, date: string): Promise<UptimeEvent[]>;
+    /**
+     * Gets the latest uptime event for a project.
+     */
+    latest(projectId: string): Promise<UptimeEvent | null>;
+    /**
+     * Summarizes daily uptime.
+     */
+    summary(projectId: string, days?: number, delayThresholdMinutes?: number): Promise<UptimeSummary[]>;
+}
+
+/**
+ * SDK configuration options.
+ */
+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;
+};
+/**
+ * Main SDK for error ingestion and uptime heartbeats.
+ */
+declare class ObservaSDK {
+    /**
+     * Uptime API (heartbeats and public reads).
+     */
+    readonly uptime: UptimeApi;
+    /**
+     * Event ingestion API.
+     */
+    readonly ingest: IngestApi;
+    private readonly http;
+    /**
+     * Creates an SDK instance with required apiKey and dsnKey.
+     */
+    constructor(options: ObservaSDKOptions);
+    /**
+     * Updates the API key used by the SDK at runtime.
+     */
+    setApiKey(apiKey: string): void;
+    getProcessContext(options?: ProcessContextOptions): ProcessContext;
+    getProcessContextStatic(options?: ProcessContextStaticOptions): ProcessContextStatic;
+    getProcessContextDynamic(options?: ProcessContextDynamicOptions): ProcessContextDynamic;
+}
+
+/**
+ * Additional data to enrich SDK errors.
+ */
+type ErrorDetails = {
+    status?: number;
+    code?: string;
+    details?: unknown;
+    retryAfter?: number;
+};
+/**
+ * Base SDK error.
+ */
+declare class SdkError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    /**
+     * Creates an error with optional metadata.
+     */
+    constructor(message: string, details?: ErrorDetails);
+}
+/**
+ * Input validation error.
+ */
+declare class ValidationError extends SdkError {
+}
+/**
+ * Authentication error.
+ */
+declare class AuthError extends SdkError {
+}
+/**
+ * Error caused by insufficient permissions.
+ */
+declare class ForbiddenError extends SdkError {
+}
+/**
+ * Error when a resource does not exist.
+ */
+declare class NotFoundError extends SdkError {
+}
+/**
+ * Error caused by a state conflict.
+ */
+declare class ConflictError extends SdkError {
+}
+/**
+ * Error caused by rate limiting.
+ */
+declare class RateLimitError extends SdkError {
+    readonly retryAfter?: number;
+    constructor(message: string, details?: ErrorDetails);
+}
+/**
+ * Server-side error.
+ */
+declare class ServerError extends SdkError {
+}
+/**
+ * Network error.
+ */
+declare class NetworkError extends SdkError {
+}
+/**
+ * Request timeout error.
+ */
+declare class TimeoutError extends SdkError {
+}
+
+export { AuthError, type AuthMode, ConflictError, ForbiddenError, HttpClient, type HttpClientOptions, IngestApi, type IngestEvent, type IngestEventContext, type IngestException, type IngestLevel, type IngestNormalizationOptions, type IngestRequest, type IngestResponse, NetworkError, NotFoundError, ObservaSDK, type ObservaSDKOptions, type ProcessContext, type ProcessContextDynamic, type ProcessContextDynamicOptions, type ProcessContextOptions, type ProcessContextStatic, type ProcessContextStaticOptions, RateLimitError, type RequestContext, type RequestOptions, type RetryPolicy, SdkError, ServerError, type Stacktrace, type StacktraceFrame, TimeoutError, UptimeApi, type UptimeEvent, type UptimeHeartbeatInput, type UptimeStatus, type UptimeSummary, ValidationError, getProcessContext, getProcessContextDynamic, getProcessContextStatic };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClC;;GAEG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAE9C;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C;;GAEG;AACH,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjG;;GAEG;AACH,OAAO,EACL,QAAQ,EACR,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAA;AAEtB;;GAEG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE5C;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACrG;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC5I,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClC;;GAEG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAE9C;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C;;GAEG;AACH,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjG;;GAEG;AACH,OAAO,EACL,QAAQ,EACR,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAA;AAEtB;;GAEG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAElE;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACrG;;GAEG;AACH,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA"}