@fe-blackbox/shared

Shared schemas and TypeScript types for the FE-Blackbox ecosystem.

Installation

npm install @fe-blackbox/shared

Note: This is an internal shared package used across the FE-Blackbox monorepo. Install it directly if you are building a custom collector or need type-safe validation for incident payloads.

Overview

@fe-blackbox/shared provides Zod schemas and inferred TypeScript types that define the data contract between the FE-Blackbox SDK, plugins, and the collector service.

Exported Schemas

| Schema | Description | | --- | --- | | incidentPayloadSchema | Full incident report payload (the core data structure) | | incidentReasonSchema | Enum of incident reasons (white-screen, manual, runtime-error, resource-error, api-error) | | consoleEntrySchema | Captured console log entry | | runtimeErrorSchema | Runtime error with stack trace | | resourceEntrySchema | Resource loading entry | | requestEntrySchema | Network request entry | | domSummarySchema | DOM snapshot summary | | whiteScreenEvidenceSchema | White-screen detection evidence | | performanceSummarySchema | Navigation timing metrics | | symbolicatedFrameSchema | Source-mapped stack frame | | attachmentPayloadSchema | Attachment (screenshot, replay, custom) | | issueSchema | Aggregated issue record | | issueStatusSchema | Issue status enum (open, resolved, ignored) | | incidentRecordSchema | Stored incident record with metadata | | privacySchema | Privacy configuration |

Exported Types

All types are inferred from their corresponding schemas via z.infer:

IncidentPayload, IncidentReason, IncidentRecord, Issue, IssueStatus, ConsoleEntry, RuntimeErrorEntry, ResourceEntry, RequestEntry, DomSummary, WhiteScreenEvidence, SymbolicatedFrame, AttachmentPayload

Plugin Interface

The package also exports the FEBlackboxPlugin interface used to build SDK plugins:

import type { FEBlackboxPlugin } from '@fe-blackbox/shared';

const myPlugin: FEBlackboxPlugin = {
  name: 'my-plugin',
  setup(client) { /* called on SDK init */ },
  beforeReport(payload) { /* mutate or filter payload */ return payload; },
  afterReport(payload, response) { /* post-report hook */ },
  destroy() { /* cleanup */ }
};

Usage Example

import { incidentPayloadSchema } from '@fe-blackbox/shared';

const result = incidentPayloadSchema.safeParse(incomingData);
if (result.success) {
  // result.data is fully typed as IncidentPayload
}

License

MIT