SDK Reference | Revclust Docs

Canonical Import

Use this SDK entrypoint:

import "package:revclust_flutter_sdk/revclust_flutter.dart";

This reference covers the SDK exported by revclust_flutter.dart.

Initialization

The SDK client is app-scoped. Start it once with Revclust.initialize(...) and keep the returned client for the rest of the process.

final Revclust revclust = await Revclust.initialize(
  RevclustConfig(
    projectKey: "rpk_...",
  ),
);

Optional release/build metadata can be added once the first capture works:

final Revclust revclust = await Revclust.initialize(
  RevclustConfig(
    projectKey: "rpk_...",
    releaseStage: RevclustAppReleaseStage.production,
    appVersion: "1.4.2",
    build: "14207",
    gitSha: "49948bf",
  ),
);

Type	Purpose
`Revclust`	App-scoped SDK client.
`RevclustConfig`	Startup config containing `projectKey` and optional release/build metadata.
`RevclustAppReleaseStage`	App release metadata: `development`, `staging`, `production`, `test`, or a validated custom value.

appVersion, build, and gitSha are reproduction-condition metadata attached to captured packs. They do not affect bootstrap routing or SDK key availability.

Core Methods

These are the main methods exposed on Revclust:

Member	Purpose
`status`	Current SDK state.
`uploadSnapshot`	Current best-known queue and upload state.
`diagnostics`	Privacy-safe snapshot of bootstrap state, origin, last status, and safe error details.
`uploadEvents`	Broadcast stream of later upload lifecycle events.
`captureInvariantFailure(failure)`	Capture one app-owned factual invariant failure.
`enableDioCapture(dio)`	Optional network hook API. Not part of the default hosted setup path.
`setStateSnapshotProvider(provider)`	Registers the bounded state payload attached to later captures.
`recordUiIntent(...)`	Records one UI intent event for the current evidence buffer.
`recordScreenTransition(...)`	Records one screen transition event for the current evidence buffer.
`enableUnhandledExceptionCapture()`	Optional unhandled-exception hook API. Not part of the default hosted setup path.

State Snapshot Provider

setStateSnapshotProvider(...) accepts a synchronous RevclustStateSnapshotProvider. The provider returns a RevclustStateSnapshot with two small maps: appState and dataState.

revclust.setStateSnapshotProvider(() {
  return const RevclustStateSnapshot(
    appState: <String, Object?>{
      "screen": "checkout",
      "step": "payment",
    },
    dataState: <String, Object?>{
      "orderRef": "ord_ref_7d82b1",
      "currency": "GBP",
    },
  );
});

Invariant Failure Model

App-owned captures use one RevclustInvariantFailure. The failure is a factual oracle: what failure class occurred, what primary subject it concerns, what was expected, and what was observed.

The public API does not ask app code for authored incident prose. Do not wire reason, signature, reproHint, stepLabel, or relevantIds for new app-owned captures. Legacy packs may still contain older trigger fields, but new captures should use failureKind, subject, expected, and observed.

Type	Purpose
`RevclustInvariantFailure.failureKind`	Stable failure class, title, and grouping key.
`RevclustInvariantFailure.subject`	Primary reproduction anchor, represented by `RevclustSubject(kind, value)`.
`RevclustInvariantFailure.expected`	Required non-empty factual invariant object.
`RevclustInvariantFailure.observed`	Required non-empty factual observed object.

final RevclustInvariantFailure failure = RevclustInvariantFailure(
  failureKind: "checkout_confirmation_mismatch",
  subject: RevclustSubject(kind: "order_ref", value: "ord_ref_7d82b1"),
  expected: <String, Object?>{
    "order_status": "confirmed",
  },
  observed: <String, Object?>{
    "order_status": "retrying",
    "last_action": "submit_order",
  },
);

Immediate Capture Outcomes

captureInvariantFailure(...) returns a RevclustCaptureOutcome immediately. That outcome is separate from later upload events.

Outcome	Meaning
`RevclustCaptureQueued`	Capture was built and stored for upload handling. Includes `captureId`.
`RevclustCaptureBlocked`	Capture was blocked before a real capture existed. Includes `status` and optional `message`.
`RevclustCaptureBuildFailed`	Capture reached build but failed before queueing. Includes `captureId` and optional `message`.
`RevclustCapturePersistenceFailed`	Capture built but could not be stored in the local queue. Includes `captureId` and optional `message`.

Status

RevclustStatus is the main SDK state.

Status	Meaning
`disabled`	`Revclust.initialize(...)` has not completed in this process yet.
`initializing`	Bootstrap or local capture setup is still in flight.
`ready`	Setup is healthy.
`degraded`	Setup is unhealthy but not fully broken. Upload connectivity may be down, or local capture may have failed during startup.
`misconfigured`	The SDK key is missing, malformed, or otherwise invalid for bootstrap.
`notProvisioned`	The SDK key is well-formed but unavailable or revoked.
`uploadBlocked`	Local queueing is still available, but upload is blocked right now.

Upload Snapshot

uploadSnapshot exposes the current queue state and the best-known coarse last error.

Member	Meaning
`pendingCount`	Number of captures waiting to upload.
`uploadingCount`	Number of captures currently uploading.
`lastErrorCode`	Best-known coarse queue or upload failure after the latest problem.

RevclustUploadErrorCode can be one of:

Error code	Meaning
`transportUnavailable`	Upload connectivity is unavailable.
`auth`	Upload access is blocked, expired, or otherwise unusable.
`misconfiguration`	Config is invalid for the current setup.
`invalidRequest`	The backend rejected the payload or request shape.
`unsupportedSchema`	The backend rejected the pack schema version.
`blobTooLarge`	The payload exceeded current hosted size limits.
`internalError`	Local capture or the backend failed unexpectedly.

Upload Events

uploadEvents is the later lifecycle stream for a queued capture.

Event	Meaning
`RevclustUploadStarted`	Upload work began for a queued capture.
`RevclustUploadAccepted`	The backend accepted the capture. Includes `RevclustAcceptedResult`.
`RevclustUploadRejected`	The backend rejected the capture. Includes `RevclustRejectionCode` and optional `message`.
`RevclustTransportFailure`	Upload failed before accept or reject was received. Includes `statusCode`, `message`, and `retryable`.

RevclustAcceptedResult exposes:

Member	Meaning
`packId`	Incident identifier.
`schemaVersion`	Accepted pack schema version.
`blobBytesGzip`	Gzipped pack size acknowledged by the backend.
`acceptedAt`	Local time the SDK confirmed hosted acceptance.
`viewerUrl`	Optional direct viewer URL for the accepted incident.

RevclustRejectionCode can be one of:

Rejection code	Meaning
`auth`	The backend rejected authorization.
`misconfiguration`	The backend rejected the key or setup state.
`invalidRequest`	The backend rejected request or payload shape.
`unsupportedSchema`	The backend rejected the schema version.
`blobTooLarge`	The backend rejected the pack size.
`internalError`	The backend failed unexpectedly.