cluebase

Types reference

Every type the SDK exports. Both packages ship the same definitions.

CluebaseUser

The signed-in end user, supplied by you. Only id is required, and it is your own identifier for that person, never shown to them. It is also the key a data-deletion request is answered against.

typescript
interface CluebaseUser {
  id: string
  email?: string
  name?: string
  metadata?: Record<string, string | number | boolean>
}
metadata is flat, deliberately.Values must be a string, number, or boolean. Nested objects and arrays are rejected by the type and dropped at runtime with a warning in development, so an entire user record cannot be posted through a field meant for a few flags.

CluebaseConfig

The provider's options. See Configuration for what each one does.

typescript
interface CluebaseConfig {
  apiKey: string
  apiEndpoint?: string
  environment?: 'development' | 'production'
  sessionId?: string
  identity?: boolean          // default true
  onError?: (report: CluebaseErrorReport) => void
  sanitize?: (text: string) => string
}

CluebaseErrorReport

What is sent for a captured error, and what onError receives.

typescript
interface CluebaseErrorReport {
  errorName?: string
  errorMessage: string
  errorStack?: string
  componentStack?: string
  errorType?: CluebaseErrorType
  visitorId?: string
  user?: CluebaseUser
  context: CluebaseErrorContext
}

Identity rides as a distinct user object rather than being merged into context, so it can be validated, stored, and deleted as one thing.

CluebaseErrorContext

typescript
interface CluebaseErrorContext {
  url: string
  userAgent: string
  sessionId?: string
  timestamp: string
  additionalContext?: string
  httpStatus?: number
  integration?: string
}

CluebaseErrorType

How the error was captured. Set automatically for everything except a manual report.

typescript
type CluebaseErrorType =
  | 'api_error'            // a request returned a non-2xx status
  | 'network_timeout'      // aborted, timed out, or the connection dropped
  | 'payment_integration'  // failure against a known payment host
  | 'render_crash'         // caught by the page-level boundary
  | 'component_crash'      // caught by a local CluebaseBoundary
  | 'unhandled_rejection'
  | 'global_error'
  | 'generic'              // a manual report with no other signal

Ingest responses

What the server answers with. Use isRenderableIngest() rather than checking the variants by hand: a rate-limited or suppressed report has no conversation to show, and both mean the same thing to a caller.

typescript
type CluebaseIngestResponse =
  | CluebaseIngestResult        // { incidentId, incidentToken, opening, history? }
  | CluebaseIngestRateLimited   // { rateLimited: true, retryAfter? }
  | CluebaseIngestSuppressed    // { widgetSuppressed: true }

Others

  • CluebaseConversationMessage: one turn of a transcript
  • WidgetTheme: the per-project look configured in your dashboard
  • CluebaseBoundaryProps, CluebaseReportExtras, InjectOverlayOptions

Next steps

PreviousClient SDK