@atlaskit/editor-synced-block-provider 8.2.0 → 8.3.0

package/dist/types/utils/errorHandling.d.ts

@@ -38,14 +38,106 @@ export type ErrorAttributionAttributes = {
  * helper stays pure and trivially unit-testable for both gate states.
  */
 export declare const buildErrorAttribution: (gateEnabled: boolean, error?: string, statusCode?: number) => ErrorAttributionAttributes | undefined;
-export declare const getErrorPayload: <T extends ACTION_SUBJECT_ID>(actionSubjectId: T, error: string, resourceId?: string, sourceProduct?: string, attribution?: ErrorAttributionAttributes) => OperationalAEP<ACTION.ERROR, ACTION_SUBJECT.SYNCED_BLOCK, T, {
+/**
+ * The set of categorical failure reasons emitted on synced-block fetch/subscribe
+ * operational error events (EDITOR-7862). Extends the write-path
+ * {@link SyncBlockErrorReason} set with read-path-specific buckets so the analytics
+ * dashboard can break fetch failures down by cause instead of regex-matching the
+ * free-text `error` blob.
+ *
+ * The read path surfaces several causes the write-path `SyncBlockError` enum does not
+ * model (benign source-state transitions, permission denials, WebSocket lifecycle, and
+ * client-side readiness errors), so those are added here. Known `SyncBlockError` enum
+ * values (`not_found`, `forbidden`, ...) still pass through unchanged.
+ */
+export type SyncBlockFetchErrorReason = SyncBlockErrorReason | 'source_deleted' | 'source_unpublished' | 'source_unsynced' | 'source_not_found' | 'permission_denied' | 'unauthenticated' | 'websocket_drop' | 'websocket_exhausted' | 'network' | 'data_provider_not_ready';
+/**
+ * Fetch reasons that represent benign (working-as-designed) outcomes rather than genuine
+ * system failures. The dashboard uses this to compute a "true error rate" by excluding
+ * benign reasons via the structured `reason` attribute instead of brittle free-text regex
+ * (EDITOR-7862).
+ */
+export declare const FETCH_BENIGN_REASONS: ReadonlySet<SyncBlockFetchErrorReason>;
+/**
+ * Maps a fetch/subscribe `error` field — which may be a {@link SyncBlockError} enum
+ * value, a {@link DeletionReason} value, or an arbitrary free-text/JSON blob — to a
+ * stable categorical {@link SyncBlockFetchErrorReason} for analytics grouping.
+ *
+ * Resolution order:
+ * 1. Known `SyncBlockError` enum value → passed through (via {@link classifyErrorReason}).
+ * 2. Known free-text substring → mapped to a fetch-specific bucket.
+ * 3. Anything else (including opaque blobs like `errored`-only payloads or
+ *    `ErrorEvent: "undefined"`) → `'unknown'`, so the dashboard never groups on free text.
+ *
+ * Note: the bare string `'errored'` IS a `SyncBlockError` enum value and therefore
+ * classifies as `'errored'` (not `'unknown'`); only genuinely unrecognised strings
+ * collapse to `'unknown'`.
+ */
+export declare const classifyFetchErrorReason: (error?: string) => SyncBlockFetchErrorReason;
+/**
+ * Extra, optional analytics attributes describing WHY a fetch/subscribe synced-block
+ * action failed. Spread conditionally so we never emit `undefined` keys (EDITOR-7862).
+ *
+ * Adds `benign` on top of the shared {@link ErrorAttributionAttributes} so the dashboard
+ * can compute a true error rate (`genuine / total`) without any free-text regex.
+ */
+export type FetchErrorAttributionAttributes = {
+    /**
+     * Categorical fetch failure cause for dashboard grouping. Declared standalone (not via
+     * `ErrorAttributionAttributes & ...`) because intersecting two `reason?` properties
+     * narrows the type to the write-path {@link SyncBlockErrorReason}; we need the wider
+     * {@link SyncBlockFetchErrorReason} here (EDITOR-7862).
+     */
+    reason?: SyncBlockFetchErrorReason;
+    /** Backend HTTP status code when the failure came from a `BlockError`. */
+    statusCode?: number;
+    /**
+     * Whether the reason is a benign/working-as-designed outcome (not a true failure).
+     * Required (not optional) so this type structurally discriminates fetch attribution
+     * from the write-path {@link ErrorAttributionAttributes}; this lets {@link getErrorPayload}
+     * overload-resolve the correct (wider) `reason` type per path. `buildFetchErrorAttribution`
+     * always sets it, so requiring it costs nothing.
+     */
+    benign: boolean;
+};
+/**
+ * Builds the {@link FetchErrorAttributionAttributes} for a failed fetch/subscribe
+ * synced-block operation from the raw `error` field and optional backend `statusCode`.
+ * Returns `undefined` when the `platform_editor_blocks_patch_3` gate is OFF, so the new
+ * `reason`/`statusCode`/`benign` attributes are only emitted once the gate is rolled out
+ * (EDITOR-7862). The existing free-text `error` attribute is always left unchanged.
+ *
+ * `gateEnabled` is injected by the caller (the store managers evaluate `fg(...)`) so this
+ * helper stays pure and trivially unit-testable for both gate states.
+ */
+export declare const buildFetchErrorAttribution: (gateEnabled: boolean, error?: string, statusCode?: number) => FetchErrorAttributionAttributes | undefined;
+/**
+ * Shared operational ERROR payload builder for synced-block events.
+ *
+ * Overloaded so the emitted `reason` type stays accurate per path (raised in review on
+ * EDITOR-7862): fetch/subscribe callers pass a {@link FetchErrorAttributionAttributes}
+ * (discriminated by its required `benign` field) and get the wider
+ * {@link SyncBlockFetchErrorReason}; write-path callers pass an
+ * {@link ErrorAttributionAttributes} (or nothing) and keep the narrower
+ * {@link SyncBlockErrorReason}, so write-path payloads never claim to carry fetch-only
+ * buckets like `source_deleted` they never emit.
+ */
+export declare function getErrorPayload<T extends ACTION_SUBJECT_ID>(actionSubjectId: T, error: string, resourceId: string | undefined, sourceProduct: string | undefined, attribution: FetchErrorAttributionAttributes): OperationalAEP<ACTION.ERROR, ACTION_SUBJECT.SYNCED_BLOCK, T, {
+    error: string;
+    resourceId?: string;
+    sourceProduct?: string;
+    reason?: SyncBlockFetchErrorReason;
+    statusCode?: number;
+    benign?: boolean;
+}>;
+export declare function getErrorPayload<T extends ACTION_SUBJECT_ID>(actionSubjectId: T, error: string, resourceId?: string, sourceProduct?: string, attribution?: ErrorAttributionAttributes): OperationalAEP<ACTION.ERROR, ACTION_SUBJECT.SYNCED_BLOCK, T, {
     error: string;
     resourceId?: string;
     sourceProduct?: string;
     reason?: SyncBlockErrorReason;
     statusCode?: number;
 }>;
-export declare const fetchErrorPayload: (error: string, resourceId?: string, sourceProduct?: string) => RendererSyncBlockEventPayload;
+export declare const fetchErrorPayload: (error: string, resourceId?: string, sourceProduct?: string, attribution?: FetchErrorAttributionAttributes) => RendererSyncBlockEventPayload;
 export declare const getSourceInfoErrorPayload: (error: string, resourceId?: string, sourceProduct?: string) => RendererSyncBlockEventPayload;
 export declare const updateErrorPayload: (error: string, resourceId?: string, sourceProduct?: string, attribution?: ErrorAttributionAttributes) => SyncBlockEventPayload;
 export declare const updateReferenceErrorPayload: (error: string, resourceId?: string, sourceProduct?: string, attribution?: ErrorAttributionAttributes) => RendererSyncBlockEventPayload;

package/package.json

@@ -21,7 +21,7 @@
 		"@atlaskit/editor-prosemirror": "^8.0.0",
 		"@atlaskit/node-data-provider": "^13.0.0",
 		"@atlaskit/platform-feature-flags": "^2.0.0",
-		"@atlaskit/tmp-editor-statsig": "^114.0.0",
+		"@atlaskit/tmp-editor-statsig": "^114.4.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"graphql-ws": "^5.14.2",
@@ -30,7 +30,7 @@
 		"uuid": "^3.1.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^116.15.0",
+		"@atlaskit/editor-common": "^116.17.0",
 		"react": "^18.2.0"
 	},
 	"devDependencies": {
@@ -74,7 +74,7 @@
 		}
 	},
 	"name": "@atlaskit/editor-synced-block-provider",
-	"version": "8.2.0",
+	"version": "8.3.0",
 	"description": "Synced Block Provider for @atlaskit/editor-plugin-synced-block",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",