@atlaskit/editor-synced-block-provider 3.12.0 → 3.13.0

package/dist/esm/utils/resolveSyncBlockInstance.js

@@ -34,7 +34,7 @@ export var resolveSyncBlockInstance = function resolveSyncBlockInstance(oldResul
       sourceTitle: ((_newResult$data2 = newResult.data) === null || _newResult$data2 === void 0 ? void 0 : _newResult$data2.sourceTitle) || ((_oldResult$data2 = oldResult.data) === null || _oldResult$data2 === void 0 ? void 0 : _oldResult$data2.sourceTitle) || undefined
     }, fg('platform_synced_block_dogfooding') && {
       sourceSubType: ((_newResult$data3 = newResult.data) === null || _newResult$data3 === void 0 ? void 0 : _newResult$data3.sourceSubType) || ((_oldResult$data3 = oldResult.data) === null || _oldResult$data3 === void 0 ? void 0 : _oldResult$data3.sourceSubType) || undefined,
-      onSamePage: ((_newResult$data4 = newResult.data) === null || _newResult$data4 === void 0 ? void 0 : _newResult$data4.onSamePage) || ((_oldResult$data4 = oldResult.data) === null || _oldResult$data4 === void 0 ? void 0 : _oldResult$data4.onSamePage) || undefined
+      onSameDocument: ((_newResult$data4 = newResult.data) === null || _newResult$data4 === void 0 ? void 0 : _newResult$data4.onSameDocument) || ((_oldResult$data4 = oldResult.data) === null || _oldResult$data4 === void 0 ? void 0 : _oldResult$data4.onSameDocument) || undefined
     })
   });
 };

package/dist/types/clients/block-service/blockService.d.ts

@@ -1,4 +1,4 @@
-import type { ReferenceSyncBlockResponse, SyncBlockProduct } from '../../common/types';
+import type { ReferenceSyncBlockResponse, SyncBlockProduct, SyncBlockStatus } from '../../common/types';
 export type BlockContentResponse = {
     blockAri: string;
     blockInstanceId: string;
@@ -7,7 +7,7 @@ export type BlockContentResponse = {
     createdBy: string;
     product: SyncBlockProduct;
     sourceAri: string;
-    status: 'active' | 'deleted';
+    status: SyncBlockStatus;
     version: number;
 };
 export type ErrorResponse = {

package/dist/types/clients/block-service/blockSubscription.d.ts

@@ -0,0 +1,38 @@
+import type { ADFEntity } from '@atlaskit/adf-utils/types';
+import type { SyncBlockProduct } from '../../common/types';
+export type BlockSubscriptionPayload = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: string;
+    contentUpdatedAt?: number;
+    createdAt: number;
+    createdBy: string;
+    deletionReason?: string;
+    product: string;
+    sourceAri: string;
+    status: string;
+};
+export type ParsedBlockSubscriptionData = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: ADFEntity[];
+    createdAt?: string;
+    createdBy: string;
+    product: SyncBlockProduct;
+    resourceId: string;
+    sourceAri: string;
+    status: string;
+};
+type SubscriptionCallback = (data: ParsedBlockSubscriptionData) => void;
+type ErrorCallback = (error: Error) => void;
+type Unsubscribe = () => void;
+/**
+ * Creates a GraphQL subscription to block updates using the shared graphql-ws client.
+ *
+ * @param blockAri - The full block ARI to subscribe to (ari:cloud:blocks:{cloudId}:synced-block/{resourceId})
+ * @param onData - Callback function invoked when block data is updated
+ * @param onError - Optional callback function invoked on subscription errors
+ * @returns Unsubscribe function to close the subscription
+ */
+export declare const subscribeToBlockUpdates: (blockAri: string, onData: SubscriptionCallback, onError?: ErrorCallback) => Unsubscribe;
+export {};

package/dist/types/clients/jira/sourceInfo.d.ts

@@ -0,0 +1,2 @@
+import type { SyncBlockSourceInfo } from '../../providers/types';
+export declare const fetchJiraWorkItemInfo: (workItemAri: string, hasAccess: boolean) => Promise<SyncBlockSourceInfo | undefined>;

package/dist/types/common/types.d.ts

@@ -5,6 +5,7 @@ import type { SYNC_BLOCK_PRODUCTS } from './consts';
 export type BlockInstanceId = string;
 export type ResourceId = string;
 export type SyncBlockProduct = (typeof SYNC_BLOCK_PRODUCTS)[number];
+export type SyncBlockStatus = 'active' | 'deleted' | 'unpublished';
 export type SyncBlockAttrs = {
     localId: BlockInstanceId;
     resourceId: ResourceId;
@@ -34,7 +35,7 @@ export interface SyncBlockData {
     /**
      * Whether the block is on the same page as the source block
      */
-    onSamePage?: boolean;
+    onSameDocument?: boolean;
     product?: SyncBlockProduct;
     /**
      * The ARI of the block. E.G ari:cloud:blocks:<cloudId>:synced-block/<product>/<pageId>/<resourceId>
@@ -45,6 +46,7 @@ export interface SyncBlockData {
     sourceTitle?: string;
     sourceURL?: string;
     updatedAt?: string;
+    status?: SyncBlockStatus;
 }
 export interface ReferenceSyncBlockResponse {
     blockAri: string;
@@ -55,7 +57,7 @@ export interface ReferenceSyncBlockResponse {
 }
 export interface ReferenceSyncBlock extends ReferenceSyncBlockResponse {
     hasAccess: boolean;
-    onSamePage: boolean;
+    onSameDocument: boolean;
 }
 export type ReferenceSyncBlockData = {
     error?: SyncBlockError;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 export { rebaseTransaction } from './common/rebase-transaction';
 export { SyncBlockError } from './common/types';
-export type { SyncBlockData, SyncBlockNode, SyncBlockProduct, BlockInstanceId, SyncBlockAttrs, ReferenceSyncBlockData, ReferencesSourceInfo } from './common/types';
+export type { ResourceId, SyncBlockData, SyncBlockNode, SyncBlockProduct, SyncBlockStatus, BlockInstanceId, SyncBlockAttrs, ReferenceSyncBlockData, ReferencesSourceInfo } from './common/types';
 export { useFetchSyncBlockData, type UseFetchSyncBlockDataResult, } from './hooks/useFetchSyncBlockData';
 export { useFetchSyncBlockTitle } from './hooks/useFetchSyncBlockTitle';
 export { useHandleContentChanges } from './hooks/useHandleContentChanges';
@@ -11,7 +11,7 @@ export { getJiraWorkItemAri, getJiraWorkItemIdFromAri } from './clients/jira/ari
 export { useMemoizedBlockServiceAPIProviders, useMemoizedBlockServiceFetchOnlyAPIProvider, } from './providers/block-service/blockServiceAPI';
 export { fetchConfluencePageInfo } from './clients/confluence/sourceInfo';
 export { SyncBlockProvider as SyncedBlockProvider, useMemoizedSyncedBlockProvider, } from './providers/syncBlockProvider';
-export type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, SyncBlockDataProvider, SyncBlockInstance, MediaEmojiProviderOptions, SyncedBlockRendererProviderOptions, SyncBlockRendererProviderCreator, SyncedBlockRendererDataProviders, UpdateReferenceSyncBlockResult, WriteSyncBlockResult, SyncBlockParentInfo, SyncBlockSourceInfo, } from './providers/types';
+export type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, BlockSubscriptionErrorCallback, BlockUpdateCallback, SyncBlockDataProvider, SyncBlockInstance, MediaEmojiProviderOptions, SyncedBlockRendererProviderOptions, SyncBlockRendererProviderCreator, SyncedBlockRendererDataProviders, Unsubscribe, UpdateReferenceSyncBlockResult, WriteSyncBlockResult, SyncBlockParentInfo, SyncBlockSourceInfo, } from './providers/types';
 export { type ReferenceSyncBlockStoreManager } from './store-manager/referenceSyncBlockStoreManager';
 export { SyncBlockStoreManager, useMemoizedSyncBlockStoreManager, } from './store-manager/syncBlockStoreManager';
 export { resolveSyncBlockInstance } from './utils/resolveSyncBlockInstance';

package/dist/types/providers/block-service/blockServiceAPI.d.ts

@@ -44,6 +44,14 @@ declare class BlockServiceADFFetchProvider implements ADFFetchProvider {
      * @returns Array of SyncBlockInstance results
      */
     batchFetchData(blockNodeIdentifiers: BlockNodeIdentifiers[]): Promise<SyncBlockInstance[]>;
+    /**
+     * Subscribes to real-time updates for a specific block using GraphQL WebSocket subscriptions.
+     * @param resourceId - The resource ID of the block to subscribe to
+     * @param onUpdate - Callback function invoked when the block is updated
+     * @param onError - Optional callback function invoked on subscription errors
+     * @returns Unsubscribe function to stop receiving updates
+     */
+    subscribeToBlockUpdates(resourceId: ResourceId, onUpdate: (data: SyncBlockInstance) => void, onError?: (error: Error) => void): () => void;
 }
 interface BlockServiceADFWriteProviderProps {
     cloudId: string;

package/dist/types/providers/syncBlockProvider.d.ts

@@ -1,7 +1,7 @@
 import type { RendererSyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
 import type { JSONNode } from '@atlaskit/editor-json-transformer/types';
 import { type BlockInstanceId, type ReferenceSyncBlockData, type ResourceId, type SyncBlockAttrs, type SyncBlockData, type SyncBlockNode, type SyncBlockProduct } from '../common/types';
-import { SyncBlockDataProvider, type ADFFetchProvider, type ADFWriteProvider, type DeleteSyncBlockResult, type SyncBlockInstance, type SyncBlockParentInfo, type SyncBlockSourceInfo, type SyncedBlockRendererProviderOptions, type UpdateReferenceSyncBlockResult, type WriteSyncBlockResult } from './types';
+import { SyncBlockDataProvider, type ADFFetchProvider, type ADFWriteProvider, type BlockSubscriptionErrorCallback, type BlockUpdateCallback, type DeleteSyncBlockResult, type SyncBlockInstance, type SyncBlockParentInfo, type SyncBlockSourceInfo, type SyncedBlockRendererProviderOptions, type Unsubscribe, type UpdateReferenceSyncBlockResult, type WriteSyncBlockResult } from './types';
 export declare class SyncBlockProvider extends SyncBlockDataProvider {
     name: string;
     private fetchProvider;
@@ -91,6 +91,14 @@ export declare class SyncBlockProvider extends SyncBlockDataProvider {
     retrieveSyncBlockParentInfo(sourceAri: string, sourceProduct: SyncBlockProduct): SyncBlockParentInfo | undefined;
     updateReferenceData(blocks: SyncBlockAttrs[], noContent?: boolean): Promise<UpdateReferenceSyncBlockResult>;
     fetchReferences(resourceId: string, isSource: boolean): Promise<ReferenceSyncBlockData>;
+    /**
+     * Subscribes to real-time updates for a specific block.
+     * @param resourceId - The resource ID of the block to subscribe to
+     * @param onUpdate - Callback function invoked when the block is updated
+     * @param onError - Optional callback function invoked on subscription errors
+     * @returns Unsubscribe function to stop receiving updates, or undefined if not supported
+     */
+    subscribeToBlockUpdates(resourceId: string, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback): Unsubscribe | undefined;
 }
 type UseMemoizedSyncedBlockProviderProps = {
     fetchProvider: ADFFetchProvider;

package/dist/types/providers/types.d.ts

@@ -5,10 +5,6 @@ import type { MentionProvider } from '@atlaskit/mention/types';
 import { NodeDataProvider } from '@atlaskit/node-data-provider';
 import type { TaskDecisionProvider } from '@atlaskit/task-decision/types';
 import type { SyncBlockData, ResourceId, SyncBlockError, SyncBlockNode, SyncBlockProduct, BlockInstanceId, SyncBlockAttrs, ReferenceSyncBlockData } from '../common/types';
-export type BlockNodeIdentifiers = {
-    blockInstanceId: string;
-    resourceId: string;
-};
 /**
  * The instance of a sync block, containing its data and metadata.
  * Mainly used for representing the state of a sync block after fetching from a data provider.
@@ -33,7 +29,7 @@ export type SyncBlockSourceInfo = {
      * Whether the source info is for a source synced block
      */
     isSource?: boolean;
-    onSamePage?: boolean;
+    onSameDocument?: boolean;
     productType?: SyncBlockProduct;
     sourceAri: string;
     subType?: string | null;
@@ -56,10 +52,21 @@ export type UpdateReferenceSyncBlockResult = {
     error?: string;
     success: boolean;
 };
+export type BlockNodeIdentifiers = {
+    blockInstanceId: string;
+    resourceId: string;
+};
+export type BlockUpdateCallback = (data: SyncBlockInstance) => void;
+export type BlockSubscriptionErrorCallback = (error: Error) => void;
+export type Unsubscribe = () => void;
 export interface ADFFetchProvider {
     batchFetchData: (blockNodeIdentifiers: BlockNodeIdentifiers[]) => Promise<SyncBlockInstance[]>;
     fetchData: (resourceId: ResourceId) => Promise<SyncBlockInstance>;
     fetchReferences: (referenceResourceId: string) => Promise<ReferenceSyncBlockData>;
+    /**
+     * Subscribes to real-time updates for a specific block.
+     */
+    subscribeToBlockUpdates?: (resourceId: ResourceId, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback) => Unsubscribe;
 }
 export interface ADFWriteProvider {
     createData: (data: SyncBlockData) => Promise<WriteSyncBlockResult>;
@@ -88,8 +95,8 @@ export type SyncedBlockRendererDataProviders = {
 export type SyncBlockRendererProviderCreator = {
     createEmojiProvider: ((options: MediaEmojiProviderOptions) => Promise<EmojiProvider> | undefined) | undefined;
     createMediaProvider: ((options: MediaEmojiProviderOptions) => Promise<MediaProvider> | undefined) | undefined;
-    createSSRMediaProvider?: ((options: MediaEmojiProviderOptions) => MediaProvider | undefined) | undefined;
     createSmartLinkProvider: (() => Promise<CardProvider>) | undefined;
+    createSSRMediaProvider?: ((options: MediaEmojiProviderOptions) => MediaProvider | undefined) | undefined;
 };
 export type SyncedBlockRendererProviderOptions = {
     parentDataProviders?: SyncedBlockRendererDataProviders;
@@ -119,6 +126,15 @@ export declare abstract class SyncBlockDataProvider extends NodeDataProvider<Syn
     abstract generateResourceIdForReference(sourceId: ResourceId): ResourceId;
     abstract updateReferenceData(blocks: SyncBlockAttrs[], noContent?: boolean): Promise<UpdateReferenceSyncBlockResult>;
     abstract fetchReferences(resourceId: string, isSource: boolean): Promise<ReferenceSyncBlockData>;
+    /**
+     * Subscribes to real-time updates for a specific block.
+     * Returns undefined if subscriptions are not supported.
+     * @param resourceId - The resource ID of the block to subscribe to
+     * @param onUpdate - Callback function invoked when the block is updated
+     * @param onError - Optional callback function invoked on subscription errors
+     * @returns Unsubscribe function to stop receiving updates, or undefined if not supported
+     */
+    subscribeToBlockUpdates?(resourceId: ResourceId, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback): Unsubscribe | undefined;
 }
 export type SubscriptionCallback = (data: SyncBlockInstance) => void;
 export type TitleSubscriptionCallback = (title: string) => void;

package/dist/types/store-manager/referenceSyncBlockStoreManager.d.ts

@@ -17,20 +17,78 @@ export declare class ReferenceSyncBlockStoreManager {
     private syncBlockSourceInfoRequests;
     private isRefreshingSubscriptions;
     private pendingCacheDeletions;
+    private graphqlSubscriptions;
+    private useRealTimeSubscriptions;
+    private subscriptionChangeListeners;
     fetchExperience: Experience | undefined;
     private fetchSourceInfoExperience;
     private saveExperience;
     constructor(dataProvider?: SyncBlockDataProvider);
+    /**
+     * Enables or disables real-time GraphQL subscriptions for block updates.
+     * When enabled, the store manager will subscribe to real-time updates
+     * instead of relying on polling.
+     * @param enabled - Whether to enable real-time subscriptions
+     */
+    setRealTimeSubscriptionsEnabled(enabled: boolean): void;
+    /**
+     * Checks if real-time subscriptions are currently enabled.
+     */
+    isRealTimeSubscriptionsEnabled(): boolean;
+    /**
+     * Returns all resource IDs that are currently subscribed to.
+     * Used by React components to render subscription components.
+     */
+    getSubscribedResourceIds(): ResourceId[];
+    /**
+     * Registers a listener that will be called when subscriptions change.
+     * @param listener - Callback function to invoke when subscriptions change
+     * @returns Unsubscribe function to remove the listener
+     */
+    onSubscriptionsChanged(listener: () => void): () => void;
+    /**
+     * Notifies all subscription change listeners.
+     */
+    private notifySubscriptionChangeListeners;
+    /**
+     * Handles incoming data from a GraphQL subscription.
+     * Called by React subscription components when they receive updates.
+     * @param syncBlockInstance - The updated sync block instance
+     */
+    handleSubscriptionUpdate(syncBlockInstance: SyncBlockInstance): void;
     setFireAnalyticsEvent(fireAnalyticsEvent?: (payload: RendererSyncBlockEventPayload) => void): void;
-    setExperiences(fetchExperience: Experience, fetchSourceInfoExperience: Experience, saveExperience: Experience): void;
     generateResourceIdForReference(sourceId: ResourceId): ResourceId;
     updateFireAnalyticsEvent(fireAnalyticsEvent?: (payload: RendererSyncBlockEventPayload) => void): void;
     getInitialSyncBlockData(resourceId: ResourceId): SyncBlockInstance | undefined;
     /**
      * Refreshes the subscriptions for all sync blocks.
+     * This is a fallback polling mechanism when real-time subscriptions are not enabled.
      * @returns {Promise<void>}
      */
     refreshSubscriptions(): Promise<void>;
+    /**
+     * Sets up a GraphQL subscription for a specific block.
+     * @param resourceId - The resource ID of the block to subscribe to
+     */
+    private setupGraphQLSubscription;
+    /**
+     * Handles updates received from GraphQL subscriptions.
+     * @param syncBlockInstance - The updated sync block instance
+     */
+    private handleGraphQLSubscriptionUpdate;
+    /**
+     * Cleans up the GraphQL subscription for a specific block.
+     * @param resourceId - The resource ID of the block to unsubscribe from
+     */
+    private cleanupGraphQLSubscription;
+    /**
+     * Sets up GraphQL subscriptions for all currently subscribed blocks.
+     */
+    private setupGraphQLSubscriptionsForAllBlocks;
+    /**
+     * Cleans up all GraphQL subscriptions.
+     */
+    private cleanupAllGraphQLSubscriptions;
     fetchSyncBlockSourceInfo(resourceId: ResourceId): Promise<SyncBlockSourceInfo | undefined>;
     /**
      * Fetch sync block data for a given array of sync block nodes.

package/dist/types/store-manager/sourceSyncBlockStoreManager.d.ts

@@ -1,5 +1,4 @@
 import { type SyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
-import type { Experience } from '@atlaskit/editor-common/experiences';
 import { type Node as PMNode } from '@atlaskit/editor-prosemirror/model';
 import { type ResourceId, type SyncBlockAttrs, type BlockInstanceId } from '../common/types';
 import type { SyncBlockDataProvider, SyncBlockSourceInfo } from '../providers/types';
@@ -16,14 +15,11 @@ export declare class SourceSyncBlockStoreManager {
     private deletionRetryInfo?;
     private pendingResourceId?;
     private creationCallback?;
-    createExperience: Experience | undefined;
+    private createExperience;
     private saveExperience;
     private deleteExperience;
     constructor(dataProvider?: SyncBlockDataProvider);
     setFireAnalyticsEvent(fireAnalyticsEvent?: (payload: SyncBlockEventPayload) => void): void;
-    setCreateExperience(createExperience: Experience): void;
-    setSaveExperience(saveExperience: Experience): void;
-    setDeleteExperience(deleteExperience: Experience): void;
     isSourceBlock(node: PMNode): boolean;
     /**
      * Add/update a sync block node to/from the local cache

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

@@ -1,13 +1,18 @@
 import { ACTION, ACTION_SUBJECT, ACTION_SUBJECT_ID, type RendererSyncBlockEventPayload, type OperationalAEP, type SyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
 export declare const stringifyError: (error: unknown) => string | undefined;
-export declare const getErrorPayload: <T extends ACTION_SUBJECT_ID>(actionSubjectId: T, error: string) => OperationalAEP<ACTION.ERROR, ACTION_SUBJECT.SYNCED_BLOCK, T, {
+export declare const getErrorPayload: <T extends ACTION_SUBJECT_ID>(actionSubjectId: T, error: string, resourceId?: string) => OperationalAEP<ACTION.ERROR, ACTION_SUBJECT.SYNCED_BLOCK, T, {
     error: string;
+    resourceId?: string;
 }>;
-export declare const fetchErrorPayload: (error: string) => RendererSyncBlockEventPayload;
-export declare const getSourceInfoErrorPayload: (error: string) => RendererSyncBlockEventPayload;
-export declare const updateErrorPayload: (error: string) => SyncBlockEventPayload;
-export declare const updateReferenceErrorPayload: (error: string) => RendererSyncBlockEventPayload;
-export declare const createErrorPayload: (error: string) => SyncBlockEventPayload;
-export declare const deleteErrorPayload: (error: string) => SyncBlockEventPayload;
-export declare const updateCacheErrorPayload: (error: string) => SyncBlockEventPayload;
-export declare const fetchReferencesErrorPayload: (error: string) => SyncBlockEventPayload;
+export declare const fetchErrorPayload: (error: string, resourceId?: string) => RendererSyncBlockEventPayload;
+export declare const getSourceInfoErrorPayload: (error: string, resourceId?: string) => RendererSyncBlockEventPayload;
+export declare const updateErrorPayload: (error: string, resourceId?: string) => SyncBlockEventPayload;
+export declare const updateReferenceErrorPayload: (error: string, resourceId?: string) => RendererSyncBlockEventPayload;
+export declare const createErrorPayload: (error: string, resourceId?: string) => SyncBlockEventPayload;
+export declare const deleteErrorPayload: (error: string, resourceId?: string) => SyncBlockEventPayload;
+export declare const updateCacheErrorPayload: (error: string, resourceId?: string) => SyncBlockEventPayload;
+export declare const fetchReferencesErrorPayload: (error: string, resourceId?: string) => SyncBlockEventPayload;
+export declare const fetchSuccessPayload: (resourceId: string, blockInstanceId?: string, sourceProduct?: string) => RendererSyncBlockEventPayload;
+export declare const createSuccessPayload: (resourceId: string) => SyncBlockEventPayload;
+export declare const updateSuccessPayload: (resourceId: string, hasReference?: boolean) => SyncBlockEventPayload;
+export declare const deleteSuccessPayload: (resourceId: string) => SyncBlockEventPayload;

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

@@ -0,0 +1,51 @@
+import { type DispatchAnalyticsEvent, type SyncBlockEventPayload, type RendererSyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
+import { Experience } from '@atlaskit/editor-common/experiences';
+export declare const createExperienceDispatcher: (fireAnalyticsEvent?: ((payload: SyncBlockEventPayload) => void) | ((payload: RendererSyncBlockEventPayload) => void)) => DispatchAnalyticsEvent;
+/**
+ * This experience tracks when a source sync block is saved to the BE.
+ *
+ * Start: When the flush source sync block function is called.
+ * Success: When the sync block save is successful within the timeout duration of start.
+ * Failure: When the timeout duration passes without the sync block being successfully saved
+ */
+export declare const getSaveSourceExperience: (fireAnalyticsEvent?: (payload: SyncBlockEventPayload) => void) => Experience;
+/**
+ * This experience tracks when a reference sync block is saved to the BE.
+ *
+ * Start: When the flush sync block function is called.
+ * Success: When the sync block save is successful within the timeout duration of start.
+ * Failure: When the timeout duration passes without the sync block being successfully saved
+ */
+export declare const getSaveReferenceExperience: (fireAnalyticsEvent?: (payload: RendererSyncBlockEventPayload) => void) => Experience;
+/**
+ * This experience tracks when a reference sync block data is fetched from the BE.
+ *
+ * Start: When the fetchNodesData function is called.
+ * Success: When the fetching the data is successful within the timeout duration of start.
+ * Failure: When the timeout duration passes without the data being successfully fetched, or the fetch fails
+ */
+export declare const getFetchExperience: (fireAnalyticsEvent?: (payload: RendererSyncBlockEventPayload) => void) => Experience;
+/**
+ * This experience tracks when a reference sync block source info data (title, url) is fetched from the BE.
+ *
+ * Start: When the fetchSourceInfo function is called.
+ * Success: When the fetching the data is successful within the timeout duration of start.
+ * Failure: When the timeout duration passes without the data being successfully fetched, or the fetch fails
+ */
+export declare const getFetchSourceInfoExperience: (fireAnalyticsEvent?: (payload: RendererSyncBlockEventPayload) => void) => Experience;
+/**
+ * This experience tracks when a source sync block is deleted from the BE.
+ *
+ * Start: When the fetchSourceInfo function is called.
+ * Success: When the fetching the data is successful within the timeout duration of start.
+ * Failure: When the timeout duration passes without the data being successfully fetched, or the fetch fails
+ */
+export declare const getDeleteSourceExperience: (fireAnalyticsEvent?: (payload: SyncBlockEventPayload) => void) => Experience;
+/**
+ * This experience tracks when a source sync block is created and registered to the BE.
+ *
+ * Start: When the fetchSourceInfo function is called.
+ * Success: When the fetching the data is successful within the timeout duration of start.
+ * Failure: When the timeout duration passes without the data being successfully fetched, or the fetch fails
+ */
+export declare const getCreateSourceExperience: (fireAnalyticsEvent?: (payload: SyncBlockEventPayload) => void) => Experience;

package/dist/types-ts4.5/clients/block-service/blockService.d.ts

@@ -1,4 +1,4 @@
-import type { ReferenceSyncBlockResponse, SyncBlockProduct } from '../../common/types';
+import type { ReferenceSyncBlockResponse, SyncBlockProduct, SyncBlockStatus } from '../../common/types';
 export type BlockContentResponse = {
     blockAri: string;
     blockInstanceId: string;
@@ -7,7 +7,7 @@ export type BlockContentResponse = {
     createdBy: string;
     product: SyncBlockProduct;
     sourceAri: string;
-    status: 'active' | 'deleted';
+    status: SyncBlockStatus;
     version: number;
 };
 export type ErrorResponse = {

package/dist/types-ts4.5/clients/block-service/blockSubscription.d.ts

@@ -0,0 +1,38 @@
+import type { ADFEntity } from '@atlaskit/adf-utils/types';
+import type { SyncBlockProduct } from '../../common/types';
+export type BlockSubscriptionPayload = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: string;
+    contentUpdatedAt?: number;
+    createdAt: number;
+    createdBy: string;
+    deletionReason?: string;
+    product: string;
+    sourceAri: string;
+    status: string;
+};
+export type ParsedBlockSubscriptionData = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: ADFEntity[];
+    createdAt?: string;
+    createdBy: string;
+    product: SyncBlockProduct;
+    resourceId: string;
+    sourceAri: string;
+    status: string;
+};
+type SubscriptionCallback = (data: ParsedBlockSubscriptionData) => void;
+type ErrorCallback = (error: Error) => void;
+type Unsubscribe = () => void;
+/**
+ * Creates a GraphQL subscription to block updates using the shared graphql-ws client.
+ *
+ * @param blockAri - The full block ARI to subscribe to (ari:cloud:blocks:{cloudId}:synced-block/{resourceId})
+ * @param onData - Callback function invoked when block data is updated
+ * @param onError - Optional callback function invoked on subscription errors
+ * @returns Unsubscribe function to close the subscription
+ */
+export declare const subscribeToBlockUpdates: (blockAri: string, onData: SubscriptionCallback, onError?: ErrorCallback) => Unsubscribe;
+export {};

package/dist/types-ts4.5/clients/jira/sourceInfo.d.ts

@@ -0,0 +1,2 @@
+import type { SyncBlockSourceInfo } from '../../providers/types';
+export declare const fetchJiraWorkItemInfo: (workItemAri: string, hasAccess: boolean) => Promise<SyncBlockSourceInfo | undefined>;

package/dist/types-ts4.5/common/types.d.ts

@@ -5,6 +5,7 @@ import type { SYNC_BLOCK_PRODUCTS } from './consts';
 export type BlockInstanceId = string;
 export type ResourceId = string;
 export type SyncBlockProduct = (typeof SYNC_BLOCK_PRODUCTS)[number];
+export type SyncBlockStatus = 'active' | 'deleted' | 'unpublished';
 export type SyncBlockAttrs = {
     localId: BlockInstanceId;
     resourceId: ResourceId;
@@ -34,7 +35,7 @@ export interface SyncBlockData {
     /**
      * Whether the block is on the same page as the source block
      */
-    onSamePage?: boolean;
+    onSameDocument?: boolean;
     product?: SyncBlockProduct;
     /**
      * The ARI of the block. E.G ari:cloud:blocks:<cloudId>:synced-block/<product>/<pageId>/<resourceId>
@@ -45,6 +46,7 @@ export interface SyncBlockData {
     sourceTitle?: string;
     sourceURL?: string;
     updatedAt?: string;
+    status?: SyncBlockStatus;
 }
 export interface ReferenceSyncBlockResponse {
     blockAri: string;
@@ -55,7 +57,7 @@ export interface ReferenceSyncBlockResponse {
 }
 export interface ReferenceSyncBlock extends ReferenceSyncBlockResponse {
     hasAccess: boolean;
-    onSamePage: boolean;
+    onSameDocument: boolean;
 }
 export type ReferenceSyncBlockData = {
     error?: SyncBlockError;

package/dist/types-ts4.5/index.d.ts

@@ -1,6 +1,6 @@
 export { rebaseTransaction } from './common/rebase-transaction';
 export { SyncBlockError } from './common/types';
-export type { SyncBlockData, SyncBlockNode, SyncBlockProduct, BlockInstanceId, SyncBlockAttrs, ReferenceSyncBlockData, ReferencesSourceInfo } from './common/types';
+export type { ResourceId, SyncBlockData, SyncBlockNode, SyncBlockProduct, SyncBlockStatus, BlockInstanceId, SyncBlockAttrs, ReferenceSyncBlockData, ReferencesSourceInfo } from './common/types';
 export { useFetchSyncBlockData, type UseFetchSyncBlockDataResult, } from './hooks/useFetchSyncBlockData';
 export { useFetchSyncBlockTitle } from './hooks/useFetchSyncBlockTitle';
 export { useHandleContentChanges } from './hooks/useHandleContentChanges';
@@ -11,7 +11,7 @@ export { getJiraWorkItemAri, getJiraWorkItemIdFromAri } from './clients/jira/ari
 export { useMemoizedBlockServiceAPIProviders, useMemoizedBlockServiceFetchOnlyAPIProvider, } from './providers/block-service/blockServiceAPI';
 export { fetchConfluencePageInfo } from './clients/confluence/sourceInfo';
 export { SyncBlockProvider as SyncedBlockProvider, useMemoizedSyncedBlockProvider, } from './providers/syncBlockProvider';
-export type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, SyncBlockDataProvider, SyncBlockInstance, MediaEmojiProviderOptions, SyncedBlockRendererProviderOptions, SyncBlockRendererProviderCreator, SyncedBlockRendererDataProviders, UpdateReferenceSyncBlockResult, WriteSyncBlockResult, SyncBlockParentInfo, SyncBlockSourceInfo, } from './providers/types';
+export type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, BlockSubscriptionErrorCallback, BlockUpdateCallback, SyncBlockDataProvider, SyncBlockInstance, MediaEmojiProviderOptions, SyncedBlockRendererProviderOptions, SyncBlockRendererProviderCreator, SyncedBlockRendererDataProviders, Unsubscribe, UpdateReferenceSyncBlockResult, WriteSyncBlockResult, SyncBlockParentInfo, SyncBlockSourceInfo, } from './providers/types';
 export { type ReferenceSyncBlockStoreManager } from './store-manager/referenceSyncBlockStoreManager';
 export { SyncBlockStoreManager, useMemoizedSyncBlockStoreManager, } from './store-manager/syncBlockStoreManager';
 export { resolveSyncBlockInstance } from './utils/resolveSyncBlockInstance';

package/dist/types-ts4.5/providers/block-service/blockServiceAPI.d.ts

@@ -44,6 +44,14 @@ declare class BlockServiceADFFetchProvider implements ADFFetchProvider {
      * @returns Array of SyncBlockInstance results
      */
     batchFetchData(blockNodeIdentifiers: BlockNodeIdentifiers[]): Promise<SyncBlockInstance[]>;
+    /**
+     * Subscribes to real-time updates for a specific block using GraphQL WebSocket subscriptions.
+     * @param resourceId - The resource ID of the block to subscribe to
+     * @param onUpdate - Callback function invoked when the block is updated
+     * @param onError - Optional callback function invoked on subscription errors
+     * @returns Unsubscribe function to stop receiving updates
+     */
+    subscribeToBlockUpdates(resourceId: ResourceId, onUpdate: (data: SyncBlockInstance) => void, onError?: (error: Error) => void): () => void;
 }
 interface BlockServiceADFWriteProviderProps {
     cloudId: string;

package/dist/types-ts4.5/providers/syncBlockProvider.d.ts

@@ -1,7 +1,7 @@
 import type { RendererSyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
 import type { JSONNode } from '@atlaskit/editor-json-transformer/types';
 import { type BlockInstanceId, type ReferenceSyncBlockData, type ResourceId, type SyncBlockAttrs, type SyncBlockData, type SyncBlockNode, type SyncBlockProduct } from '../common/types';
-import { SyncBlockDataProvider, type ADFFetchProvider, type ADFWriteProvider, type DeleteSyncBlockResult, type SyncBlockInstance, type SyncBlockParentInfo, type SyncBlockSourceInfo, type SyncedBlockRendererProviderOptions, type UpdateReferenceSyncBlockResult, type WriteSyncBlockResult } from './types';
+import { SyncBlockDataProvider, type ADFFetchProvider, type ADFWriteProvider, type BlockSubscriptionErrorCallback, type BlockUpdateCallback, type DeleteSyncBlockResult, type SyncBlockInstance, type SyncBlockParentInfo, type SyncBlockSourceInfo, type SyncedBlockRendererProviderOptions, type Unsubscribe, type UpdateReferenceSyncBlockResult, type WriteSyncBlockResult } from './types';
 export declare class SyncBlockProvider extends SyncBlockDataProvider {
     name: string;
     private fetchProvider;
@@ -91,6 +91,14 @@ export declare class SyncBlockProvider extends SyncBlockDataProvider {
     retrieveSyncBlockParentInfo(sourceAri: string, sourceProduct: SyncBlockProduct): SyncBlockParentInfo | undefined;
     updateReferenceData(blocks: SyncBlockAttrs[], noContent?: boolean): Promise<UpdateReferenceSyncBlockResult>;
     fetchReferences(resourceId: string, isSource: boolean): Promise<ReferenceSyncBlockData>;
+    /**
+     * Subscribes to real-time updates for a specific block.
+     * @param resourceId - The resource ID of the block to subscribe to
+     * @param onUpdate - Callback function invoked when the block is updated
+     * @param onError - Optional callback function invoked on subscription errors
+     * @returns Unsubscribe function to stop receiving updates, or undefined if not supported
+     */
+    subscribeToBlockUpdates(resourceId: string, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback): Unsubscribe | undefined;
 }
 type UseMemoizedSyncedBlockProviderProps = {
     fetchProvider: ADFFetchProvider;

package/dist/types-ts4.5/providers/types.d.ts

@@ -5,10 +5,6 @@ import type { MentionProvider } from '@atlaskit/mention/types';
 import { NodeDataProvider } from '@atlaskit/node-data-provider';
 import type { TaskDecisionProvider } from '@atlaskit/task-decision/types';
 import type { SyncBlockData, ResourceId, SyncBlockError, SyncBlockNode, SyncBlockProduct, BlockInstanceId, SyncBlockAttrs, ReferenceSyncBlockData } from '../common/types';
-export type BlockNodeIdentifiers = {
-    blockInstanceId: string;
-    resourceId: string;
-};
 /**
  * The instance of a sync block, containing its data and metadata.
  * Mainly used for representing the state of a sync block after fetching from a data provider.
@@ -33,7 +29,7 @@ export type SyncBlockSourceInfo = {
      * Whether the source info is for a source synced block
      */
     isSource?: boolean;
-    onSamePage?: boolean;
+    onSameDocument?: boolean;
     productType?: SyncBlockProduct;
     sourceAri: string;
     subType?: string | null;
@@ -56,10 +52,21 @@ export type UpdateReferenceSyncBlockResult = {
     error?: string;
     success: boolean;
 };
+export type BlockNodeIdentifiers = {
+    blockInstanceId: string;
+    resourceId: string;
+};
+export type BlockUpdateCallback = (data: SyncBlockInstance) => void;
+export type BlockSubscriptionErrorCallback = (error: Error) => void;
+export type Unsubscribe = () => void;
 export interface ADFFetchProvider {
     batchFetchData: (blockNodeIdentifiers: BlockNodeIdentifiers[]) => Promise<SyncBlockInstance[]>;
     fetchData: (resourceId: ResourceId) => Promise<SyncBlockInstance>;
     fetchReferences: (referenceResourceId: string) => Promise<ReferenceSyncBlockData>;
+    /**
+     * Subscribes to real-time updates for a specific block.
+     */
+    subscribeToBlockUpdates?: (resourceId: ResourceId, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback) => Unsubscribe;
 }
 export interface ADFWriteProvider {
     createData: (data: SyncBlockData) => Promise<WriteSyncBlockResult>;
@@ -88,8 +95,8 @@ export type SyncedBlockRendererDataProviders = {
 export type SyncBlockRendererProviderCreator = {
     createEmojiProvider: ((options: MediaEmojiProviderOptions) => Promise<EmojiProvider> | undefined) | undefined;
     createMediaProvider: ((options: MediaEmojiProviderOptions) => Promise<MediaProvider> | undefined) | undefined;
-    createSSRMediaProvider?: ((options: MediaEmojiProviderOptions) => MediaProvider | undefined) | undefined;
     createSmartLinkProvider: (() => Promise<CardProvider>) | undefined;
+    createSSRMediaProvider?: ((options: MediaEmojiProviderOptions) => MediaProvider | undefined) | undefined;
 };
 export type SyncedBlockRendererProviderOptions = {
     parentDataProviders?: SyncedBlockRendererDataProviders;
@@ -119,6 +126,15 @@ export declare abstract class SyncBlockDataProvider extends NodeDataProvider<Syn
     abstract generateResourceIdForReference(sourceId: ResourceId): ResourceId;
     abstract updateReferenceData(blocks: SyncBlockAttrs[], noContent?: boolean): Promise<UpdateReferenceSyncBlockResult>;
     abstract fetchReferences(resourceId: string, isSource: boolean): Promise<ReferenceSyncBlockData>;
+    /**
+     * Subscribes to real-time updates for a specific block.
+     * Returns undefined if subscriptions are not supported.
+     * @param resourceId - The resource ID of the block to subscribe to
+     * @param onUpdate - Callback function invoked when the block is updated
+     * @param onError - Optional callback function invoked on subscription errors
+     * @returns Unsubscribe function to stop receiving updates, or undefined if not supported
+     */
+    subscribeToBlockUpdates?(resourceId: ResourceId, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback): Unsubscribe | undefined;
 }
 export type SubscriptionCallback = (data: SyncBlockInstance) => void;
 export type TitleSubscriptionCallback = (title: string) => void;