Revclust

Canonical Import

Use this SDK entrypoint:

import "package:revclust_flutter/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 release metadata attached to captured incidents. They do not affect SDK connectivity 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)`	Registers a Dio client for bounded request outcomes and best-effort normalized paths. App-selected route templates replace inferred paths.
`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.

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. It describes the failure class, the specific subject involved, what was expected, and what was observed.

New captures use failureKind, subject, expected, and observed rather than authored incident prose.

Type	Purpose
`RevclustInvariantFailure.failureKind`	Stable failure class, title, and grouping key.
`RevclustInvariantFailure.subject`	Privacy-safe entity or flow involved in the failure, 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.
`quotaExceeded`	The workspace has reached its captured-incident allowance.
`unsupportedSchema`	The backend rejected the incident schema version.
`blobTooLarge`	The payload exceeded current 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 incident schema version.
`blobBytesGzip`	Gzipped incident payload size acknowledged by the service.
`acceptedAt`	Local time when the SDK confirmed the incident was accepted.
`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.
`quotaExceeded`	The workspace has reached its captured-incident allowance.
`unsupportedSchema`	The backend rejected the schema version.
`blobTooLarge`	The backend rejected the payload because it exceeded the size limit.
`internalError`	The backend failed unexpectedly.

Canonical Import

Use this SDK entrypoint:

import "package:revclust_flutter/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 release metadata attached to captured incidents. They do not affect SDK connectivity 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)`	Registers a Dio client for bounded request outcomes and best-effort normalized paths. App-selected route templates replace inferred paths.
`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.

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. It describes the failure class, the specific subject involved, what was expected, and what was observed.

New captures use failureKind, subject, expected, and observed rather than authored incident prose.

Type	Purpose
`RevclustInvariantFailure.failureKind`	Stable failure class, title, and grouping key.
`RevclustInvariantFailure.subject`	Privacy-safe entity or flow involved in the failure, 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.
`quotaExceeded`	The workspace has reached its captured-incident allowance.
`unsupportedSchema`	The backend rejected the incident schema version.
`blobTooLarge`	The payload exceeded current 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 incident schema version.
`blobBytesGzip`	Gzipped incident payload size acknowledged by the service.
`acceptedAt`	Local time when the SDK confirmed the incident was accepted.
`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.
`quotaExceeded`	The workspace has reached its captured-incident allowance.
`unsupportedSchema`	The backend rejected the schema version.
`blobTooLarge`	The backend rejected the payload because it exceeded the size limit.
`internalError`	The backend failed unexpectedly.

SDK Reference

Canonical Import

Initialization

Core Methods

State Snapshot Provider

Invariant Failure Model

Immediate Capture Outcomes

Status

Upload Snapshot

Upload Events

SDK Reference

Canonical Import

Initialization

Core Methods

State Snapshot Provider

Invariant Failure Model

Immediate Capture Outcomes

Status

Upload Snapshot

Upload Events