@dispatchitapp/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,288 @@
+type Level = "fatal" | "error" | "warning" | "info" | "debug";
+type TagValue = string | number | boolean | null;
+type Tags = Record<string, TagValue>;
+interface DispatchFrame {
+    abs_path?: string | null;
+    filename?: string | null;
+    function?: string | null;
+    lineno: number;
+    colno?: number | null;
+    in_app?: boolean;
+    pre_context?: string[];
+    context_line?: string;
+    post_context?: string[];
+}
+interface DispatchStacktrace {
+    frames: DispatchFrame[];
+}
+interface DispatchMechanism {
+    type: string;
+    handled: boolean;
+}
+interface DispatchExceptionValue {
+    type: string;
+    value: string;
+    mechanism: DispatchMechanism;
+    stacktrace: DispatchStacktrace;
+}
+interface DispatchUser {
+    id?: string | null;
+    email?: string | null;
+    ip_address?: string | null;
+}
+interface DispatchRequest {
+    url?: string | null;
+    method?: string | null;
+    query_string?: string | null;
+    headers?: Record<string, string>;
+    data?: Record<string, unknown> | null;
+    env?: Record<string, string>;
+}
+interface DispatchSdk {
+    name: string;
+    version: string;
+}
+interface DispatchEvent {
+    event_id: string;
+    timestamp: number;
+    platform: string;
+    level: Level;
+    environment: string;
+    release?: string | null;
+    server_name?: string | null;
+    transaction?: string | null;
+    exception: {
+        values: DispatchExceptionValue[];
+    };
+    request?: DispatchRequest;
+    user?: DispatchUser;
+    tags?: Tags;
+    sdk?: DispatchSdk;
+}
+interface TicketReporter {
+    email?: string | null;
+    external_id?: string | null;
+}
+interface TicketAttachment {
+    filename?: string;
+    content_type?: string;
+    data: string;
+}
+interface TicketBody {
+    description: string;
+    title?: string;
+    source?: string;
+    severity?: string | null;
+    reporter?: TicketReporter | null;
+    metadata?: Record<string, unknown>;
+    screenshots?: TicketAttachment[];
+    attachments?: TicketAttachment[];
+}
+interface TicketPayload {
+    ticket: TicketBody;
+}
+interface TicketResponse {
+    id: number;
+    status: string;
+    url: string;
+}
+
+declare const DEFAULT_ENDPOINT = "https://dispatchit.app/api/v1/tickets";
+declare const DEFAULT_ENABLED_ENVIRONMENTS: string[];
+interface DispatchOptions {
+    /** Project API token (prefix dsp_live_). Required. */
+    apiKey: string;
+    /** Tickets endpoint. Default https://dispatchit.app/api/v1/tickets. */
+    endpoint?: string;
+    /** Error-ingest endpoint. Default: `endpoint` with the last path segment swapped to /store. */
+    errorEndpoint?: string;
+    /** Deploy environment. Default process.env.NODE_ENV, else "production". */
+    environment?: string;
+    /** Release identifier, e.g. a git SHA. */
+    release?: string | null;
+    /** Environments in which capture is active. Default ["production", "staging"]; [] means all. */
+    enabledEnvironments?: string[];
+    /** Master switch for exception capture. Default true. */
+    captureExceptions?: boolean;
+    /** Fraction of errors to report, 0..1. Default 1.0. */
+    errorSampleRate?: number;
+    /** Last chance to mutate or drop an event. Return null to drop. */
+    beforeSend?: ((event: DispatchEvent) => DispatchEvent | null) | null;
+    /** Static affected-user (server adapters resolve a per-request user instead). */
+    user?: DispatchUser | null;
+    /** Static tags attached to every event. */
+    tags?: Tags;
+    /** Identifies the producing SDK. Server adapters override the name (e.g. "dispatch-node"). */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    /** Log internal failures to console. Default false. */
+    debug?: boolean;
+    /** Base URL for human-facing report links. Default: the origin of `endpoint`. */
+    reportBaseUrl?: string | null;
+    /** Budget (ms) for draining the event queue at process exit; 0 skips the exit flush.
+     *  Default 3000. Mirrors the gem's shutdown_timeout (seconds there, ms here). */
+    shutdownTimeout?: number;
+}
+interface DispatchConfig {
+    apiKey: string;
+    endpoint: string;
+    errorEndpoint: string;
+    reportBaseUrl: string | null;
+    environment: string;
+    release: string | null;
+    enabledEnvironments: string[];
+    captureExceptions: boolean;
+    errorSampleRate: number;
+    beforeSend: ((event: DispatchEvent) => DispatchEvent | null) | null;
+    user: DispatchUser | null;
+    tags: Tags;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    debug: boolean;
+    shutdownTimeout: number;
+}
+declare function deriveErrorEndpoint(endpoint: string): string;
+declare function deriveReportBaseUrl(endpoint: string): string | null;
+declare function resolveConfig(options: DispatchOptions): DispatchConfig;
+declare function configured(c: DispatchConfig): boolean;
+declare function environmentEnabled(c: DispatchConfig): boolean;
+declare function errorTrackingEnabled(c: DispatchConfig): boolean;
+
+interface ReportInput {
+    /** Required. The human-readable description of the issue. */
+    description: string;
+    title?: string;
+    /** One of low/medium/high/critical. Unknown values are dropped server-side. */
+    severity?: string | null;
+    /** Origin of the report. Default "api". */
+    source?: string;
+    metadata?: Record<string, unknown>;
+    reporter?: TicketReporter | null;
+    /** Links the ticket to an already-captured error group (e.g. a request id or event_id). */
+    correlationId?: string | null;
+    attachments?: TicketAttachment[];
+}
+declare function buildTicketPayload(input: ReportInput): TicketPayload;
+
+declare const QUEUE_LIMIT = 100;
+interface Transport {
+    /** Enqueue an error event for asynchronous delivery (off the hot path). */
+    sendEvent(event: DispatchEvent): void;
+    /** Synchronously POST a ticket and return the parsed response (or null on failure). */
+    postTicket(payload: TicketPayload): Promise<TicketResponse | null>;
+    /** Resolve once the queue has drained (or the timeout elapses). */
+    flush(timeoutMs?: number): Promise<boolean>;
+}
+type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    keepalive?: boolean;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+declare function sdkHeader(config: DispatchConfig): string;
+declare class FetchTransport implements Transport {
+    protected readonly config: DispatchConfig;
+    private queue;
+    private draining;
+    private readonly fetchImpl;
+    constructor(config: DispatchConfig, fetchImpl?: FetchLike);
+    sendEvent(event: DispatchEvent): void;
+    postTicket(payload: TicketPayload): Promise<TicketResponse | null>;
+    flush(timeoutMs?: number): Promise<boolean>;
+    private kick;
+    private drain;
+    protected post(url: string, body: unknown): Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    } | null>;
+    protected warn(message: string): void;
+}
+
+interface CaptureContext {
+    level?: Level;
+    /** Defaults to true for manual capture; framework handlers pass false for unhandled errors. */
+    handled?: boolean;
+    user?: DispatchUser | null;
+    tags?: Tags;
+    request?: DispatchRequest;
+    transaction?: string | null;
+    serverName?: string | null;
+}
+interface ClientOptions extends DispatchOptions {
+    /** Override the transport (tests, or a runtime-specific transport). */
+    transport?: Transport;
+    /** The originating runtime written into event.platform. Default "javascript". */
+    platform?: string;
+    /** Injectable stack parser (e.g. the Node V8 parser, or a browser parser). */
+    parseStack?: (stack?: string | null) => DispatchFrame[];
+    /** Injectable RNG for deterministic sampling in tests. */
+    rng?: () => number;
+}
+declare class Client {
+    readonly config: DispatchConfig;
+    readonly transport: Transport;
+    private readonly platform;
+    private readonly parseStack;
+    private readonly rng;
+    constructor(options: ClientOptions);
+    captureException(error: unknown, context?: CaptureContext): void;
+    report(input: ReportInput): Promise<TicketResponse | null>;
+    flush(timeoutMs?: number): Promise<boolean>;
+    close(timeoutMs?: number): Promise<boolean>;
+}
+
+declare const MAX_CAUSES = 5;
+declare const VALUE_MAX_LENGTH = 2000;
+interface BuildEventInput {
+    config: DispatchConfig;
+    handled: boolean;
+    platform?: string;
+    level?: Level;
+    user?: DispatchUser | null;
+    tags?: Tags;
+    request?: DispatchRequest;
+    transaction?: string | null;
+    serverName?: string | null;
+    /** Injectable for runtime-specific parsing (e.g. the Node V8 parser). Defaults to core's. */
+    parseStack?: (stack?: string | null) => DispatchFrame[];
+    /** Injectable for deterministic tests. */
+    now?: () => number;
+    uuid?: () => string;
+}
+declare function buildEvent(error: unknown, input: BuildEventInput): DispatchEvent;
+
+declare const MAX_FRAMES = 100;
+declare function parseStack(stack?: string | null): DispatchFrame[];
+
+declare function sampledOut(rate: number, rng?: () => number): boolean;
+
+declare function alreadyCaptured(error: unknown): boolean;
+declare function markCaptured(error: unknown): void;
+
+declare const SDK_NAME = "dispatch-js";
+declare const SDK_VERSION = "1.0.0";
+declare const CONTRACT_VERSION = "1";
+
+/** Initialise the default client. Call once at startup. Returns it for direct use. */
+declare function init(options: ClientOptions): Client;
+/** The default client, or null if init() hasn't been called. */
+declare function getClient(): Client | null;
+/** Report a handled (or, from adapters, unhandled) exception via the default client. */
+declare function captureException(error: unknown, context?: CaptureContext): void;
+/** File a curated ticket via the default client. Resolves null if uninitialised. */
+declare function report(input: ReportInput): Promise<TicketResponse | null>;
+/** Wait for queued events to flush. Resolves true if the queue drained in time. */
+declare function flush(timeoutMs?: number): Promise<boolean>;
+/** Flush and stop using the default client. */
+declare function close(timeoutMs?: number): Promise<boolean>;
+
+export { CONTRACT_VERSION, type CaptureContext, Client, type ClientOptions, DEFAULT_ENABLED_ENVIRONMENTS, DEFAULT_ENDPOINT, type DispatchConfig, type DispatchEvent, type DispatchExceptionValue, type DispatchFrame, type DispatchMechanism, type DispatchOptions, type DispatchRequest, type DispatchSdk, type DispatchStacktrace, type DispatchUser, type FetchLike, FetchTransport, type Level, MAX_CAUSES, MAX_FRAMES, QUEUE_LIMIT, type ReportInput, SDK_NAME, SDK_VERSION, type TagValue, type Tags, type TicketAttachment, type TicketBody, type TicketPayload, type TicketReporter, type TicketResponse, type Transport, VALUE_MAX_LENGTH, alreadyCaptured, buildEvent, buildTicketPayload, captureException, close, configured, deriveErrorEndpoint, deriveReportBaseUrl, environmentEnabled, errorTrackingEnabled, flush, getClient, init, markCaptured, parseStack, report, resolveConfig, sampledOut, sdkHeader };

package/dist/index.d.ts

@@ -0,0 +1,288 @@
+type Level = "fatal" | "error" | "warning" | "info" | "debug";
+type TagValue = string | number | boolean | null;
+type Tags = Record<string, TagValue>;
+interface DispatchFrame {
+    abs_path?: string | null;
+    filename?: string | null;
+    function?: string | null;
+    lineno: number;
+    colno?: number | null;
+    in_app?: boolean;
+    pre_context?: string[];
+    context_line?: string;
+    post_context?: string[];
+}
+interface DispatchStacktrace {
+    frames: DispatchFrame[];
+}
+interface DispatchMechanism {
+    type: string;
+    handled: boolean;
+}
+interface DispatchExceptionValue {
+    type: string;
+    value: string;
+    mechanism: DispatchMechanism;
+    stacktrace: DispatchStacktrace;
+}
+interface DispatchUser {
+    id?: string | null;
+    email?: string | null;
+    ip_address?: string | null;
+}
+interface DispatchRequest {
+    url?: string | null;
+    method?: string | null;
+    query_string?: string | null;
+    headers?: Record<string, string>;
+    data?: Record<string, unknown> | null;
+    env?: Record<string, string>;
+}
+interface DispatchSdk {
+    name: string;
+    version: string;
+}
+interface DispatchEvent {
+    event_id: string;
+    timestamp: number;
+    platform: string;
+    level: Level;
+    environment: string;
+    release?: string | null;
+    server_name?: string | null;
+    transaction?: string | null;
+    exception: {
+        values: DispatchExceptionValue[];
+    };
+    request?: DispatchRequest;
+    user?: DispatchUser;
+    tags?: Tags;
+    sdk?: DispatchSdk;
+}
+interface TicketReporter {
+    email?: string | null;
+    external_id?: string | null;
+}
+interface TicketAttachment {
+    filename?: string;
+    content_type?: string;
+    data: string;
+}
+interface TicketBody {
+    description: string;
+    title?: string;
+    source?: string;
+    severity?: string | null;
+    reporter?: TicketReporter | null;
+    metadata?: Record<string, unknown>;
+    screenshots?: TicketAttachment[];
+    attachments?: TicketAttachment[];
+}
+interface TicketPayload {
+    ticket: TicketBody;
+}
+interface TicketResponse {
+    id: number;
+    status: string;
+    url: string;
+}
+
+declare const DEFAULT_ENDPOINT = "https://dispatchit.app/api/v1/tickets";
+declare const DEFAULT_ENABLED_ENVIRONMENTS: string[];
+interface DispatchOptions {
+    /** Project API token (prefix dsp_live_). Required. */
+    apiKey: string;
+    /** Tickets endpoint. Default https://dispatchit.app/api/v1/tickets. */
+    endpoint?: string;
+    /** Error-ingest endpoint. Default: `endpoint` with the last path segment swapped to /store. */
+    errorEndpoint?: string;
+    /** Deploy environment. Default process.env.NODE_ENV, else "production". */
+    environment?: string;
+    /** Release identifier, e.g. a git SHA. */
+    release?: string | null;
+    /** Environments in which capture is active. Default ["production", "staging"]; [] means all. */
+    enabledEnvironments?: string[];
+    /** Master switch for exception capture. Default true. */
+    captureExceptions?: boolean;
+    /** Fraction of errors to report, 0..1. Default 1.0. */
+    errorSampleRate?: number;
+    /** Last chance to mutate or drop an event. Return null to drop. */
+    beforeSend?: ((event: DispatchEvent) => DispatchEvent | null) | null;
+    /** Static affected-user (server adapters resolve a per-request user instead). */
+    user?: DispatchUser | null;
+    /** Static tags attached to every event. */
+    tags?: Tags;
+    /** Identifies the producing SDK. Server adapters override the name (e.g. "dispatch-node"). */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    /** Log internal failures to console. Default false. */
+    debug?: boolean;
+    /** Base URL for human-facing report links. Default: the origin of `endpoint`. */
+    reportBaseUrl?: string | null;
+    /** Budget (ms) for draining the event queue at process exit; 0 skips the exit flush.
+     *  Default 3000. Mirrors the gem's shutdown_timeout (seconds there, ms here). */
+    shutdownTimeout?: number;
+}
+interface DispatchConfig {
+    apiKey: string;
+    endpoint: string;
+    errorEndpoint: string;
+    reportBaseUrl: string | null;
+    environment: string;
+    release: string | null;
+    enabledEnvironments: string[];
+    captureExceptions: boolean;
+    errorSampleRate: number;
+    beforeSend: ((event: DispatchEvent) => DispatchEvent | null) | null;
+    user: DispatchUser | null;
+    tags: Tags;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    debug: boolean;
+    shutdownTimeout: number;
+}
+declare function deriveErrorEndpoint(endpoint: string): string;
+declare function deriveReportBaseUrl(endpoint: string): string | null;
+declare function resolveConfig(options: DispatchOptions): DispatchConfig;
+declare function configured(c: DispatchConfig): boolean;
+declare function environmentEnabled(c: DispatchConfig): boolean;
+declare function errorTrackingEnabled(c: DispatchConfig): boolean;
+
+interface ReportInput {
+    /** Required. The human-readable description of the issue. */
+    description: string;
+    title?: string;
+    /** One of low/medium/high/critical. Unknown values are dropped server-side. */
+    severity?: string | null;
+    /** Origin of the report. Default "api". */
+    source?: string;
+    metadata?: Record<string, unknown>;
+    reporter?: TicketReporter | null;
+    /** Links the ticket to an already-captured error group (e.g. a request id or event_id). */
+    correlationId?: string | null;
+    attachments?: TicketAttachment[];
+}
+declare function buildTicketPayload(input: ReportInput): TicketPayload;
+
+declare const QUEUE_LIMIT = 100;
+interface Transport {
+    /** Enqueue an error event for asynchronous delivery (off the hot path). */
+    sendEvent(event: DispatchEvent): void;
+    /** Synchronously POST a ticket and return the parsed response (or null on failure). */
+    postTicket(payload: TicketPayload): Promise<TicketResponse | null>;
+    /** Resolve once the queue has drained (or the timeout elapses). */
+    flush(timeoutMs?: number): Promise<boolean>;
+}
+type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    keepalive?: boolean;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+declare function sdkHeader(config: DispatchConfig): string;
+declare class FetchTransport implements Transport {
+    protected readonly config: DispatchConfig;
+    private queue;
+    private draining;
+    private readonly fetchImpl;
+    constructor(config: DispatchConfig, fetchImpl?: FetchLike);
+    sendEvent(event: DispatchEvent): void;
+    postTicket(payload: TicketPayload): Promise<TicketResponse | null>;
+    flush(timeoutMs?: number): Promise<boolean>;
+    private kick;
+    private drain;
+    protected post(url: string, body: unknown): Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    } | null>;
+    protected warn(message: string): void;
+}
+
+interface CaptureContext {
+    level?: Level;
+    /** Defaults to true for manual capture; framework handlers pass false for unhandled errors. */
+    handled?: boolean;
+    user?: DispatchUser | null;
+    tags?: Tags;
+    request?: DispatchRequest;
+    transaction?: string | null;
+    serverName?: string | null;
+}
+interface ClientOptions extends DispatchOptions {
+    /** Override the transport (tests, or a runtime-specific transport). */
+    transport?: Transport;
+    /** The originating runtime written into event.platform. Default "javascript". */
+    platform?: string;
+    /** Injectable stack parser (e.g. the Node V8 parser, or a browser parser). */
+    parseStack?: (stack?: string | null) => DispatchFrame[];
+    /** Injectable RNG for deterministic sampling in tests. */
+    rng?: () => number;
+}
+declare class Client {
+    readonly config: DispatchConfig;
+    readonly transport: Transport;
+    private readonly platform;
+    private readonly parseStack;
+    private readonly rng;
+    constructor(options: ClientOptions);
+    captureException(error: unknown, context?: CaptureContext): void;
+    report(input: ReportInput): Promise<TicketResponse | null>;
+    flush(timeoutMs?: number): Promise<boolean>;
+    close(timeoutMs?: number): Promise<boolean>;
+}
+
+declare const MAX_CAUSES = 5;
+declare const VALUE_MAX_LENGTH = 2000;
+interface BuildEventInput {
+    config: DispatchConfig;
+    handled: boolean;
+    platform?: string;
+    level?: Level;
+    user?: DispatchUser | null;
+    tags?: Tags;
+    request?: DispatchRequest;
+    transaction?: string | null;
+    serverName?: string | null;
+    /** Injectable for runtime-specific parsing (e.g. the Node V8 parser). Defaults to core's. */
+    parseStack?: (stack?: string | null) => DispatchFrame[];
+    /** Injectable for deterministic tests. */
+    now?: () => number;
+    uuid?: () => string;
+}
+declare function buildEvent(error: unknown, input: BuildEventInput): DispatchEvent;
+
+declare const MAX_FRAMES = 100;
+declare function parseStack(stack?: string | null): DispatchFrame[];
+
+declare function sampledOut(rate: number, rng?: () => number): boolean;
+
+declare function alreadyCaptured(error: unknown): boolean;
+declare function markCaptured(error: unknown): void;
+
+declare const SDK_NAME = "dispatch-js";
+declare const SDK_VERSION = "1.0.0";
+declare const CONTRACT_VERSION = "1";
+
+/** Initialise the default client. Call once at startup. Returns it for direct use. */
+declare function init(options: ClientOptions): Client;
+/** The default client, or null if init() hasn't been called. */
+declare function getClient(): Client | null;
+/** Report a handled (or, from adapters, unhandled) exception via the default client. */
+declare function captureException(error: unknown, context?: CaptureContext): void;
+/** File a curated ticket via the default client. Resolves null if uninitialised. */
+declare function report(input: ReportInput): Promise<TicketResponse | null>;
+/** Wait for queued events to flush. Resolves true if the queue drained in time. */
+declare function flush(timeoutMs?: number): Promise<boolean>;
+/** Flush and stop using the default client. */
+declare function close(timeoutMs?: number): Promise<boolean>;
+
+export { CONTRACT_VERSION, type CaptureContext, Client, type ClientOptions, DEFAULT_ENABLED_ENVIRONMENTS, DEFAULT_ENDPOINT, type DispatchConfig, type DispatchEvent, type DispatchExceptionValue, type DispatchFrame, type DispatchMechanism, type DispatchOptions, type DispatchRequest, type DispatchSdk, type DispatchStacktrace, type DispatchUser, type FetchLike, FetchTransport, type Level, MAX_CAUSES, MAX_FRAMES, QUEUE_LIMIT, type ReportInput, SDK_NAME, SDK_VERSION, type TagValue, type Tags, type TicketAttachment, type TicketBody, type TicketPayload, type TicketReporter, type TicketResponse, type Transport, VALUE_MAX_LENGTH, alreadyCaptured, buildEvent, buildTicketPayload, captureException, close, configured, deriveErrorEndpoint, deriveReportBaseUrl, environmentEnabled, errorTrackingEnabled, flush, getClient, init, markCaptured, parseStack, report, resolveConfig, sampledOut, sdkHeader };