@atlaskit/editor-synced-block-provider 3.30.3 → 3.30.4

package/dist/esm/clients/block-service/sharedSubscriptionUtils.js

@@ -0,0 +1,76 @@
+import { convertContentUpdatedAt } from '../../utils/utils';
+/**
+ * Shared GraphQL subscription query for block updates.
+ * This is the canonical subscription query used across all implementations.
+ */
+export var BLOCK_SERVICE_SUBSCRIPTION_QUERY = "\nsubscription EDITOR_SYNCED_BLOCK_ON_BLOCK_UPDATED($resourceId: ID!) {\n\tblockService_onBlockUpdated(resourceId: $resourceId) {\n\t\tblockAri\n\t\tblockInstanceId\n\t\tcontent\n\t\tcontentUpdatedAt\n\t\tcreatedAt\n\t\tcreatedBy\n\t\tdeletionReason\n\t\tproduct\n\t\tsourceAri\n\t\tstatus\n\t}\n}\n";
+
+/**
+ * Raw subscription payload from the GraphQL subscription.
+ * This represents the exact shape returned by the blockService_onBlockUpdated subscription.
+ */
+
+/**
+ * Parsed and normalized block subscription data.
+ * This is the standardized format used across different subscription implementations.
+ */
+
+/**
+ * Extracts the resourceId from a block ARI.
+ * Block ARI format: ari:cloud:blocks:<cloudId>:synced-block/<resourceId>
+ * @param blockAri - The block ARI string
+ * @returns The resourceId portion of the ARI
+ */
+export var extractResourceIdFromBlockAri = function extractResourceIdFromBlockAri(blockAri) {
+  // eslint-disable-next-line require-unicode-regexp
+  var match = blockAri.match(/ari:cloud:blocks:[^:]+:synced-block\/(.+)$/);
+  return (match === null || match === void 0 ? void 0 : match[1]) || null;
+};
+
+/**
+ * Converts a timestamp to ISO string.
+ * @param timestamp - Timestamp in milliseconds
+ * @returns ISO string or undefined if conversion fails
+ */
+export var convertTimestampToISOString = function convertTimestampToISOString(timestamp) {
+  if (timestamp === undefined || timestamp === null) {
+    return undefined;
+  }
+  try {
+    return new Date(timestamp).toISOString();
+  } catch (_unused) {
+    return undefined;
+  }
+};
+
+/**
+ * Parses the raw subscription payload into a standardized format.
+ * This function handles all the data transformation and error handling consistently
+ * across different subscription implementations.
+ * 
+ * @param payload - The raw subscription payload
+ * @returns Parsed block data or null if parsing fails
+ */
+export var parseSubscriptionPayload = function parseSubscriptionPayload(payload) {
+  try {
+    var resourceId = extractResourceIdFromBlockAri(payload.blockAri);
+    if (!resourceId) {
+      return null;
+    }
+    var createdAt = convertTimestampToISOString(payload.createdAt);
+    return {
+      blockAri: payload.blockAri,
+      blockInstanceId: payload.blockInstanceId,
+      content: JSON.parse(payload.content),
+      contentUpdatedAt: convertContentUpdatedAt(payload.contentUpdatedAt),
+      createdAt: createdAt,
+      createdBy: payload.createdBy,
+      product: payload.product,
+      resourceId: resourceId,
+      sourceAri: payload.sourceAri,
+      status: payload.status
+    };
+  } catch (_unused2) {
+    return null;
+  }
+};

package/dist/esm/index.js

@@ -25,6 +25,10 @@ export { SyncBlockInMemorySessionCache, syncBlockInMemorySessionCache } from './
 export { SyncBlockStoreManager, useMemoizedSyncBlockStoreManager } from './store-manager/syncBlockStoreManager';
 
 // utils
+export { BLOCK_SERVICE_SUBSCRIPTION_QUERY } from './clients/block-service/sharedSubscriptionUtils';
+export { parseSubscriptionPayload } from './clients/block-service/sharedSubscriptionUtils';
+export { convertRelayResponseToSyncBlockInstance } from './utils/relayResponseConverter';
+export { createRelayBlockSubscription, createRelaySubscriptionFunction } from './utils/relaySubscriptionUtils';
 export { resolveSyncBlockInstance } from './utils/resolveSyncBlockInstance';
 export { parseResourceId, createResourceIdForReference } from './utils/resourceId';
 export { createSyncBlockNode, convertSyncBlockPMNodeToSyncBlockData, convertSyncBlockJSONNodeToSyncBlockNode, convertPMNodesToSyncBlockNodes, getContentIdAndProductFromResourceId } from './utils/utils';

package/dist/esm/providers/block-service/blockServiceAPI.js

@@ -17,6 +17,7 @@ import { batchRetrieveSyncedBlocks, BlockError, createSyncedBlock, deleteSyncedB
 import { subscribeToBlockUpdates as subscribeToBlockUpdatesWS } from '../../clients/block-service/blockSubscription';
 import { SyncBlockError } from '../../common/types';
 import { stringifyError } from '../../utils/errorHandling';
+import { createRelaySubscriptionFunction } from '../../utils/relaySubscriptionUtils';
 import { createResourceIdForReference } from '../../utils/resourceId';
 import { convertContentUpdatedAt } from '../../utils/utils';
 var mapBlockError = function mapBlockError(error) {
@@ -422,10 +423,12 @@ export { _batchFetchData as batchFetchData };
 var BlockServiceADFFetchProvider = /*#__PURE__*/function () {
   function BlockServiceADFFetchProvider(_ref4) {
     var cloudId = _ref4.cloudId,
-      parentAri = _ref4.parentAri;
+      parentAri = _ref4.parentAri,
+      relayEnvironment = _ref4.relayEnvironment;
     _classCallCheck(this, BlockServiceADFFetchProvider);
     this.cloudId = cloudId;
     this.parentAri = parentAri;
+    this.relayEnvironment = relayEnvironment;
   }
 
   // resourceId of the reference synced block.
@@ -610,6 +613,7 @@ var BlockServiceADFFetchProvider = /*#__PURE__*/function () {
     }()
     /**
      * Subscribes to real-time updates for a specific block using GraphQL WebSocket subscriptions.
+     * If a Relay environment is provided, uses Relay subscriptions; otherwise falls back to WebSocket.
      * @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
@@ -623,6 +627,14 @@ var BlockServiceADFFetchProvider = /*#__PURE__*/function () {
         cloudId: this.cloudId,
         resourceId: resourceId
       });
+
+      // If Relay environment is available, use Relay subscriptions
+      if (this.relayEnvironment && fg('platform_synced_block_patch_3')) {
+        var relaySubscribeToBlockUpdates = createRelaySubscriptionFunction(this.cloudId, this.relayEnvironment);
+        return relaySubscribeToBlockUpdates(resourceId, onUpdate, onError);
+      }
+
+      // Fall back to WebSocket subscriptions
       return subscribeToBlockUpdatesWS(blockAri, function (parsedData) {
         // Convert ParsedBlockSubscriptionData to SyncBlockInstance
         var syncBlockInstance = {
@@ -974,11 +986,13 @@ var createBlockServiceAPIProviders = function createBlockServiceAPIProviders(_re
     parentAri = _ref6.parentAri,
     parentId = _ref6.parentId,
     product = _ref6.product,
-    getVersion = _ref6.getVersion;
+    getVersion = _ref6.getVersion,
+    relayEnvironment = _ref6.relayEnvironment;
   return {
     fetchProvider: new BlockServiceADFFetchProvider({
       cloudId: cloudId,
-      parentAri: parentAri
+      parentAri: parentAri,
+      relayEnvironment: relayEnvironment
     }),
     writeProvider: new BlockServiceADFWriteProvider({
       cloudId: cloudId,
@@ -994,16 +1008,18 @@ export var useMemoizedBlockServiceAPIProviders = function useMemoizedBlockServic
     parentAri = _ref7.parentAri,
     parentId = _ref7.parentId,
     product = _ref7.product,
-    getVersion = _ref7.getVersion;
+    getVersion = _ref7.getVersion,
+    relayEnvironment = _ref7.relayEnvironment;
   return useMemo(function () {
     return createBlockServiceAPIProviders({
       cloudId: cloudId,
       parentAri: parentAri,
       parentId: parentId,
       product: product,
-      getVersion: getVersion
+      getVersion: getVersion,
+      relayEnvironment: relayEnvironment
     });
-  }, [cloudId, parentAri, parentId, product, getVersion]);
+  }, [cloudId, parentAri, parentId, product, getVersion, relayEnvironment]);
 };
 var createBlockServiceFetchOnlyAPIProvider = function createBlockServiceFetchOnlyAPIProvider(_ref8) {
   var cloudId = _ref8.cloudId,

package/dist/esm/utils/__generated__/relaySubscriptionUtilsSubscription.graphql.js

@@ -0,0 +1,88 @@
+/**
+ * @generated SignedSource<<559b4fb25d0e5bc72be383427a939e2d>>
+ * @relayHash 38684212c43376e58fea2d6095011652
+ * @lightSyntaxTransform
+ * @nogrep
+ * @codegen-command: yarn relay
+ */
+
+/* tslint:disable */
+/* eslint-disable */
+// @ts-nocheck
+
+// @relayRequestID c84045a1f05bd1e73ade0a9d8b18462cc3dad5dcae1ebabab76b13135411c530
+
+var node = function () {
+  var v0 = [{
+      "defaultValue": null,
+      "kind": "LocalArgument",
+      "name": "resourceId"
+    }],
+    v1 = [{
+      "args": [{
+        "kind": "Variable",
+        "name": "resourceId",
+        "variableName": "resourceId"
+      }],
+      "concreteType": "BlockServiceBlockPayload",
+      "kind": "LinkedField",
+      "name": "blockService_onBlockUpdated",
+      "plural": false,
+      "selections": [{
+        "kind": "ScalarField",
+        "name": "blockAri"
+      }, {
+        "kind": "ScalarField",
+        "name": "blockInstanceId"
+      }, {
+        "kind": "ScalarField",
+        "name": "content"
+      }, {
+        "kind": "ScalarField",
+        "name": "contentUpdatedAt"
+      }, {
+        "kind": "ScalarField",
+        "name": "createdAt"
+      }, {
+        "kind": "ScalarField",
+        "name": "createdBy"
+      }, {
+        "kind": "ScalarField",
+        "name": "deletionReason"
+      }, {
+        "kind": "ScalarField",
+        "name": "product"
+      }, {
+        "kind": "ScalarField",
+        "name": "sourceAri"
+      }, {
+        "kind": "ScalarField",
+        "name": "status"
+      }]
+    }];
+  return {
+    "fragment": {
+      "argumentDefinitions": v0 /*: any*/,
+      "kind": "Fragment",
+      "name": "relaySubscriptionUtilsSubscription",
+      "selections": v1 /*: any*/,
+      "type": "Subscription"
+    },
+    "kind": "Request",
+    "operation": {
+      "argumentDefinitions": v0 /*: any*/,
+      "kind": "Operation",
+      "name": "relaySubscriptionUtilsSubscription",
+      "selections": v1 /*: any*/
+    },
+    "params": {
+      "id": "c84045a1f05bd1e73ade0a9d8b18462cc3dad5dcae1ebabab76b13135411c530",
+      "metadata": {},
+      "name": "relaySubscriptionUtilsSubscription",
+      "operationKind": "subscription",
+      "text": null
+    }
+  };
+}();
+node.hash = "6f3ebc87921555436cad753ec1aead2e";
+export default node;

package/dist/esm/utils/relayResponseConverter.js

@@ -0,0 +1,69 @@
+import { parseSubscriptionPayload } from '../clients/block-service/sharedSubscriptionUtils';
+import { normaliseSyncBlockStatus } from './validValue';
+/**
+ * Converts parsed subscription data to SyncBlockInstance format.
+ *
+ * @param parsed - The parsed subscription data
+ * @param resourceId - The resource ID for the block
+ * @returns A SyncBlockInstance
+ */
+export function convertParsedDataToSyncBlockInstance(parsed, resourceId) {
+  return {
+    data: {
+      content: parsed.content,
+      contentUpdatedAt: parsed.contentUpdatedAt,
+      resourceId: parsed.blockAri,
+      blockInstanceId: parsed.blockInstanceId,
+      sourceAri: parsed.sourceAri,
+      product: parsed.product,
+      createdAt: parsed.createdAt,
+      createdBy: parsed.createdBy,
+      status: normaliseSyncBlockStatus(parsed.status)
+    },
+    resourceId: resourceId
+  };
+}
+
+/**
+ * Converts a Relay subscription response to SyncBlockInstance format using shared parsing logic.
+
+ * @param response - The Relay subscription response containing block update data
+ * @param resourceId - The resource ID for the block
+ * @returns A SyncBlockInstance or null if parsing fails
+ * 
+ * @example
+ * ```typescript
+ * // In a Relay subscription handler
+ * onNext: (response) => {
+ *   if (response?.blockService_onBlockUpdated) {
+ *     const syncBlockInstance = convertRelayResponseToSyncBlockInstance(
+ *       response.blockService_onBlockUpdated,
+ *       resourceId,
+ *     );
+ *     if (syncBlockInstance) {
+ *       onUpdate(syncBlockInstance);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function convertRelayResponseToSyncBlockInstance(response, resourceId) {
+  var _response$contentUpda, _response$deletionRea;
+  var payload = {
+    blockAri: response.blockAri,
+    blockInstanceId: response.blockInstanceId,
+    content: response.content,
+    contentUpdatedAt: (_response$contentUpda = response.contentUpdatedAt) !== null && _response$contentUpda !== void 0 ? _response$contentUpda : undefined,
+    createdAt: response.createdAt,
+    createdBy: response.createdBy,
+    deletionReason: (_response$deletionRea = response.deletionReason) !== null && _response$deletionRea !== void 0 ? _response$deletionRea : undefined,
+    product: response.product,
+    sourceAri: response.sourceAri,
+    status: response.status
+  };
+  var parsed = parseSubscriptionPayload(payload);
+  if (!parsed) {
+    return null;
+  }
+  return convertParsedDataToSyncBlockInstance(parsed, resourceId);
+}

package/dist/esm/utils/relaySubscriptionUtils.js

@@ -0,0 +1,123 @@
+import { requestSubscription } from 'relay-runtime';
+import { generateBlockAriFromReference } from '../clients/block-service/ari';
+import { subscribeToBlockUpdates as subscribeToBlockUpdatesWS } from '../clients/block-service/blockSubscription';
+import relaySubscriptionUtilsSubscriptionDocument from './__generated__/relaySubscriptionUtilsSubscription.graphql';
+import { convertRelayResponseToSyncBlockInstance, convertParsedDataToSyncBlockInstance } from './relayResponseConverter';
+
+/**
+ * Configuration for creating a Relay block subscription.
+ */
+
+/**
+ * Creates a Relay-based block subscription without needing to wrap providers.
+ * This is a clean utility function that can be used directly in components or hooks.
+ * 
+ * @param config - Configuration for the subscription
+ * @returns An unsubscribe function to dispose the subscription
+ * 
+ * @example
+ * ```typescript
+ * const unsubscribe = createRelayBlockSubscription({
+ *   relayEnvironment: environment,
+ *   cloudId: 'my-cloud-id',
+ *   resourceId: 'my-resource-id',
+ *   onUpdate: (blockInstance) => {
+ *     console.log('Block updated:', blockInstance);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Subscription error:', error);
+ *   }
+ * });
+ * 
+ * // Later, when component unmounts or subscription is no longer needed
+ * unsubscribe();
+ * ```
+ */
+export function createRelayBlockSubscription(config) {
+  var relayEnvironment = config.relayEnvironment,
+    cloudId = config.cloudId,
+    resourceId = config.resourceId,
+    onUpdate = config.onUpdate,
+    _onError = config.onError;
+
+  // Convert resourceId to blockAri for the subscription
+  var blockAri = generateBlockAriFromReference({
+    cloudId: cloudId,
+    resourceId: resourceId
+  });
+  var subscriptionQuery = relaySubscriptionUtilsSubscriptionDocument;
+
+  // Try to use Relay subscription first
+  try {
+    var disposable = requestSubscription(relayEnvironment, {
+      subscription: subscriptionQuery,
+      variables: {
+        resourceId: blockAri
+      },
+      onNext: function onNext(response) {
+        if (response !== null && response !== void 0 && response.blockService_onBlockUpdated) {
+          var syncBlockInstance = convertRelayResponseToSyncBlockInstance(response.blockService_onBlockUpdated, resourceId);
+          if (syncBlockInstance) {
+            onUpdate(syncBlockInstance);
+          } else {
+            _onError === null || _onError === void 0 || _onError(new Error('Failed to parse Relay block subscription payload'));
+          }
+        }
+      },
+      onError: function onError(error) {
+        _onError === null || _onError === void 0 || _onError(error);
+      }
+    });
+
+    // If subscription was successfully created, return the unsubscribe function
+    if (disposable) {
+      return function () {
+        disposable.dispose();
+      };
+    }
+  } catch (error) {
+    // If requestSubscription throws, fall back to WebSocket
+    _onError === null || _onError === void 0 || _onError(error instanceof Error ? error : new Error('Relay subscription failed'));
+  }
+
+  // Fallback to WebSocket subscription when Relay subscriptions aren't available
+  return subscribeToBlockUpdatesWS(blockAri, function (parsedData) {
+    var syncBlockInstance = convertParsedDataToSyncBlockInstance(parsedData, parsedData.resourceId);
+    onUpdate(syncBlockInstance);
+  }, function (error) {
+    _onError === null || _onError === void 0 || _onError(error);
+  });
+}
+
+/**
+ * Hook-like function to create a subscription function that can be passed to providers.
+ * This creates a function with the same signature as subscribeToBlockUpdates that uses Relay.
+ * 
+ * @param cloudId - Cloud ID for generating block ARIs  
+ * @param relayEnvironment - Optional Relay environment. If not provided, will attempt to use global environment
+ * @returns A function that can be used as subscribeToBlockUpdates in provider configurations
+ * 
+ * @example
+ * ```typescript
+ * const relaySubscribeToBlockUpdates = createRelaySubscriptionFunction(cloudId, environment);
+ * 
+ * // Can be used directly as a subscribeToBlockUpdates replacement
+ * const unsubscribe = relaySubscribeToBlockUpdates(resourceId, onUpdate, onError);
+ * ```
+ */
+export function createRelaySubscriptionFunction(cloudId, relayEnvironment) {
+  return function (resourceId, onUpdate, onError) {
+    var environment = relayEnvironment;
+    if (!environment) {
+      onError === null || onError === void 0 || onError(new Error('Relay environment not available'));
+      return function () {};
+    }
+    return createRelayBlockSubscription({
+      relayEnvironment: environment,
+      cloudId: cloudId,
+      resourceId: resourceId,
+      onUpdate: onUpdate,
+      onError: onError
+    });
+  };
+}

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

@@ -1,29 +1,4 @@
-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[];
-    contentUpdatedAt?: string;
-    createdAt?: string;
-    createdBy: string;
-    product: SyncBlockProduct;
-    resourceId: string;
-    sourceAri: string;
-    status: string;
-};
+import { type ParsedBlockSubscriptionData } from './sharedSubscriptionUtils';
 type SubscriptionCallback = (data: ParsedBlockSubscriptionData) => void;
 type ErrorCallback = (error: Error) => void;
 type Unsubscribe = () => void;

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

@@ -0,0 +1,61 @@
+import type { ADFEntity } from '@atlaskit/adf-utils/types';
+import type { SyncBlockProduct } from '../../common/types';
+/**
+ * Shared GraphQL subscription query for block updates.
+ * This is the canonical subscription query used across all implementations.
+ */
+export declare const BLOCK_SERVICE_SUBSCRIPTION_QUERY = "\nsubscription EDITOR_SYNCED_BLOCK_ON_BLOCK_UPDATED($resourceId: ID!) {\n\tblockService_onBlockUpdated(resourceId: $resourceId) {\n\t\tblockAri\n\t\tblockInstanceId\n\t\tcontent\n\t\tcontentUpdatedAt\n\t\tcreatedAt\n\t\tcreatedBy\n\t\tdeletionReason\n\t\tproduct\n\t\tsourceAri\n\t\tstatus\n\t}\n}\n";
+/**
+ * Raw subscription payload from the GraphQL subscription.
+ * This represents the exact shape returned by the blockService_onBlockUpdated subscription.
+ */
+export type BlockSubscriptionPayload = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: string;
+    contentUpdatedAt?: number;
+    createdAt: number;
+    createdBy: string;
+    deletionReason?: string;
+    product: string;
+    sourceAri: string;
+    status: string;
+};
+/**
+ * Parsed and normalized block subscription data.
+ * This is the standardized format used across different subscription implementations.
+ */
+export type ParsedBlockSubscriptionData = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: ADFEntity[];
+    contentUpdatedAt?: string;
+    createdAt?: string;
+    createdBy: string;
+    product: SyncBlockProduct;
+    resourceId: string;
+    sourceAri: string;
+    status: string;
+};
+/**
+ * Extracts the resourceId from a block ARI.
+ * Block ARI format: ari:cloud:blocks:<cloudId>:synced-block/<resourceId>
+ * @param blockAri - The block ARI string
+ * @returns The resourceId portion of the ARI
+ */
+export declare const extractResourceIdFromBlockAri: (blockAri: string) => string | null;
+/**
+ * Converts a timestamp to ISO string.
+ * @param timestamp - Timestamp in milliseconds
+ * @returns ISO string or undefined if conversion fails
+ */
+export declare const convertTimestampToISOString: (timestamp?: number) => string | undefined;
+/**
+ * Parses the raw subscription payload into a standardized format.
+ * This function handles all the data transformation and error handling consistently
+ * across different subscription implementations.
+ *
+ * @param payload - The raw subscription payload
+ * @returns Parsed block data or null if parsing fails
+ */
+export declare const parseSubscriptionPayload: (payload: BlockSubscriptionPayload) => ParsedBlockSubscriptionData | null;

package/dist/types/index.d.ts

@@ -17,6 +17,10 @@ export type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, BlockSub
 export { ReferenceSyncBlockStoreManager } from './store-manager/referenceSyncBlockStoreManager';
 export { SyncBlockInMemorySessionCache, syncBlockInMemorySessionCache, } from './store-manager/syncBlockInMemorySessionCache';
 export { SyncBlockStoreManager, useMemoizedSyncBlockStoreManager, } from './store-manager/syncBlockStoreManager';
+export { BLOCK_SERVICE_SUBSCRIPTION_QUERY } from './clients/block-service/sharedSubscriptionUtils';
+export { type BlockSubscriptionPayload, parseSubscriptionPayload } from './clients/block-service/sharedSubscriptionUtils';
+export { convertRelayResponseToSyncBlockInstance, type RelayBlockUpdateResponse } from './utils/relayResponseConverter';
+export { createRelayBlockSubscription, createRelaySubscriptionFunction, type RelayBlockSubscriptionConfig } from './utils/relaySubscriptionUtils';
 export { resolveSyncBlockInstance } from './utils/resolveSyncBlockInstance';
 export { parseResourceId, createResourceIdForReference } from './utils/resourceId';
 export { createSyncBlockNode, convertSyncBlockPMNodeToSyncBlockData, convertSyncBlockJSONNodeToSyncBlockNode, convertPMNodesToSyncBlockNodes, getContentIdAndProductFromResourceId, } from './utils/utils';

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

@@ -1,3 +1,4 @@
+import type { IEnvironment } from 'relay-runtime';
 import { type BlockContentResponse } from '../../clients/block-service/blockService';
 import { SyncBlockError, type ReferenceSyncBlockData, type ResourceId, type SyncBlockAttrs, type SyncBlockData, type SyncBlockProduct } from '../../common/types';
 import type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, DeleteSyncBlockResult, SyncBlockInstance, UpdateReferenceSyncBlockResult, WriteSyncBlockResult } from '../types';
@@ -36,6 +37,7 @@ export declare const batchFetchData: (cloudId: string, parentAri: string | undef
 interface BlockServiceADFFetchProviderProps {
     cloudId: string;
     parentAri: string | undefined;
+    relayEnvironment?: IEnvironment;
 }
 /**
  * ADFFetchProvider implementation that fetches synced block data from Block Service API
@@ -43,7 +45,8 @@ interface BlockServiceADFFetchProviderProps {
 declare class BlockServiceADFFetchProvider implements ADFFetchProvider {
     private cloudId;
     private parentAri;
-    constructor({ cloudId, parentAri }: BlockServiceADFFetchProviderProps);
+    private relayEnvironment?;
+    constructor({ cloudId, parentAri, relayEnvironment }: BlockServiceADFFetchProviderProps);
     fetchData(resourceId: string): Promise<SyncBlockInstance>;
     fetchReferences(referenceResourceId: string): Promise<ReferenceSyncBlockData>;
     /**
@@ -54,6 +57,7 @@ declare class BlockServiceADFFetchProvider implements ADFFetchProvider {
     batchFetchData(blockNodeIdentifiers: BlockNodeIdentifiers[]): Promise<SyncBlockInstance[]>;
     /**
      * Subscribes to real-time updates for a specific block using GraphQL WebSocket subscriptions.
+     * If a Relay environment is provided, uses Relay subscriptions; otherwise falls back to WebSocket.
      * @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
@@ -91,8 +95,9 @@ interface BlockServiceAPIProvidersProps {
     parentAri: string | undefined;
     parentId?: string;
     product: SyncBlockProduct;
+    relayEnvironment?: IEnvironment;
 }
-export declare const useMemoizedBlockServiceAPIProviders: ({ cloudId, parentAri, parentId, product, getVersion, }: BlockServiceAPIProvidersProps) => {
+export declare const useMemoizedBlockServiceAPIProviders: ({ cloudId, parentAri, parentId, product, getVersion, relayEnvironment, }: BlockServiceAPIProvidersProps) => {
     fetchProvider: BlockServiceADFFetchProvider;
     writeProvider: BlockServiceADFWriteProvider;
 };

package/dist/types/utils/__generated__/relaySubscriptionUtilsSubscription.graphql.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @generated SignedSource<<559b4fb25d0e5bc72be383427a939e2d>>
+ * @relayHash 38684212c43376e58fea2d6095011652
+ * @lightSyntaxTransform
+ * @nogrep
+ * @codegen-command: yarn relay
+ */
+import type { ConcreteRequest } from 'relay-runtime';
+export type relaySubscriptionUtilsSubscription$variables = {
+    resourceId: string;
+};
+export type relaySubscriptionUtilsSubscription$data = {
+    readonly blockService_onBlockUpdated: {
+        readonly blockAri: string;
+        readonly blockInstanceId: string;
+        readonly content: string;
+        readonly contentUpdatedAt: number | null | undefined;
+        readonly createdAt: number;
+        readonly createdBy: string;
+        readonly deletionReason: string | null | undefined;
+        readonly product: string;
+        readonly sourceAri: string;
+        readonly status: string;
+    } | null | undefined;
+};
+export type relaySubscriptionUtilsSubscription = {
+    response: relaySubscriptionUtilsSubscription$data;
+    variables: relaySubscriptionUtilsSubscription$variables;
+};
+declare const node: ConcreteRequest;
+export default node;

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

@@ -0,0 +1,47 @@
+import { type ParsedBlockSubscriptionData } from '../clients/block-service/sharedSubscriptionUtils';
+import type { ResourceId } from '../common/types';
+import type { SyncBlockInstance } from '../providers/types';
+export type RelayBlockUpdateResponse = {
+    blockAri: string;
+    blockInstanceId: string;
+    content: string;
+    contentUpdatedAt?: number | null;
+    createdAt: number;
+    createdBy: string;
+    deletionReason?: string | null;
+    product: string;
+    sourceAri: string;
+    status: string;
+};
+/**
+ * Converts parsed subscription data to SyncBlockInstance format.
+ *
+ * @param parsed - The parsed subscription data
+ * @param resourceId - The resource ID for the block
+ * @returns A SyncBlockInstance
+ */
+export declare function convertParsedDataToSyncBlockInstance(parsed: ParsedBlockSubscriptionData, resourceId: ResourceId): SyncBlockInstance;
+/**
+ * Converts a Relay subscription response to SyncBlockInstance format using shared parsing logic.
+
+ * @param response - The Relay subscription response containing block update data
+ * @param resourceId - The resource ID for the block
+ * @returns A SyncBlockInstance or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * // In a Relay subscription handler
+ * onNext: (response) => {
+ *   if (response?.blockService_onBlockUpdated) {
+ *     const syncBlockInstance = convertRelayResponseToSyncBlockInstance(
+ *       response.blockService_onBlockUpdated,
+ *       resourceId,
+ *     );
+ *     if (syncBlockInstance) {
+ *       onUpdate(syncBlockInstance);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function convertRelayResponseToSyncBlockInstance(response: RelayBlockUpdateResponse, resourceId: ResourceId): SyncBlockInstance | null;