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

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

@@ -0,0 +1,61 @@
+import type { IEnvironment } from 'relay-runtime';
+import type { ResourceId } from '../common/types';
+import type { BlockSubscriptionErrorCallback, BlockUpdateCallback, Unsubscribe } from '../providers/types';
+/**
+ * Configuration for creating a Relay block subscription.
+ */
+export interface RelayBlockSubscriptionConfig {
+    /** Cloud ID for generating block ARIs */
+    cloudId: string;
+    /** Optional callback when subscription errors occur */
+    onError?: BlockSubscriptionErrorCallback;
+    /** Callback when block updates are received */
+    onUpdate: BlockUpdateCallback;
+    /** Relay environment to use for the subscription */
+    relayEnvironment: IEnvironment;
+    /** The resource ID to subscribe to */
+    resourceId: ResourceId;
+}
+/**
+ * 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 declare function createRelayBlockSubscription(config: RelayBlockSubscriptionConfig): Unsubscribe;
+/**
+ * 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 declare function createRelaySubscriptionFunction(cloudId: string, relayEnvironment?: IEnvironment): (resourceId: ResourceId, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback) => Unsubscribe;

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

@@ -1,3 +1,3 @@
-import type { SyncBlockProduct, SyncBlockStatus } from "../common/types";
+import type { SyncBlockProduct, SyncBlockStatus } from '../common/types';
 export declare const normaliseSyncBlockProduct: (value: string | null | undefined) => SyncBlockProduct | undefined;
 export declare const normaliseSyncBlockStatus: (value: string | null | undefined) => SyncBlockStatus | undefined;

package/dist/types-ts4.5/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-ts4.5/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-ts4.5/index.d.ts

@@ -15,7 +15,12 @@ export { fetchConfluencePageInfo } from './clients/confluence/sourceInfo';
 export { SyncedBlockProvider, useMemoizedSyncedBlockProvider } from './providers/syncBlockProvider';
 export type { ADFFetchProvider, ADFWriteProvider, BlockNodeIdentifiers, BlockSubscriptionErrorCallback, BlockUpdateCallback, SyncBlockDataProviderInterface, SyncBlockInstance, MediaEmojiProviderOptions, SyncedBlockRendererProviderOptions, SyncBlockRendererProviderCreator, SyncedBlockRendererDataProviders, Unsubscribe, UpdateReferenceSyncBlockResult, WriteSyncBlockResult, SyncBlockParentInfo, SyncBlockSourceInfo, } from './providers/types';
 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-ts4.5/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-ts4.5/store-manager/referenceSyncBlockStoreManager.d.ts

@@ -73,8 +73,8 @@ export declare class ReferenceSyncBlockStoreManager {
     generateResourceIdForReference(sourceId: ResourceId): ResourceId;
     updateFireAnalyticsEvent(fireAnalyticsEvent?: (payload: RendererSyncBlockEventPayload) => void): void;
     getInitialSyncBlockData(resourceId: ResourceId): SyncBlockInstance | undefined;
-    private updateCacheInSessionStorage;
-    private getSyncBlockDataFromSessionStorage;
+    private updateSessionCache;
+    private getFromSessionCache;
     /**
      * Refreshes the subscriptions for all sync blocks.
      * This is a fallback polling mechanism when real-time subscriptions are not enabled.
@@ -125,7 +125,7 @@ export declare class ReferenceSyncBlockStoreManager {
     getFromCache(resourceId: ResourceId): SyncBlockInstance | undefined;
     private deleteFromCache;
     private debouncedBatchedFetchSyncBlocks;
-    private setSSRDataInSessionStorage;
+    private setSSRDataInSessionCache;
     subscribeToSyncBlock(resourceId: string, localId: string, callback: SubscriptionCallback): () => void;
     subscribeToSourceTitle(node: PMNode, callback: TitleSubscriptionCallback): () => void;
     subscribe(node: PMNode, callback: SubscriptionCallback): () => void;

package/dist/types-ts4.5/store-manager/syncBlockInMemorySessionCache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * In-memory session cache for sync block data with size-based LRU eviction.
+ *
+ * Backed by a plain Map so that potentially private ADF content is never
+ * written to any browser-persistent storage (sessionStorage, localStorage,
+ * IndexedDB). The module-level singleton survives SPA transitions (no full
+ * page reload) and is naturally cleared on hard navigation or tab close.
+ *
+ * Uses JavaScript Map's insertion-order guarantee to implement LRU:
+ * on every read or write the accessed entry is moved to the end of the
+ * iteration order; when total cached size exceeds `maxSize`, the oldest
+ * (least-recently-used) entries are evicted first.
+ */
+export declare class SyncBlockInMemorySessionCache {
+    private store;
+    private currentSize;
+    private maxSize;
+    constructor(maxSize?: number);
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export declare const syncBlockInMemorySessionCache: SyncBlockInMemorySessionCache;

package/dist/types-ts4.5/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-ts4.5/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;

package/dist/types-ts4.5/utils/relaySubscriptionUtils.d.ts

@@ -0,0 +1,61 @@
+import type { IEnvironment } from 'relay-runtime';
+import type { ResourceId } from '../common/types';
+import type { BlockSubscriptionErrorCallback, BlockUpdateCallback, Unsubscribe } from '../providers/types';
+/**
+ * Configuration for creating a Relay block subscription.
+ */
+export interface RelayBlockSubscriptionConfig {
+    /** Cloud ID for generating block ARIs */
+    cloudId: string;
+    /** Optional callback when subscription errors occur */
+    onError?: BlockSubscriptionErrorCallback;
+    /** Callback when block updates are received */
+    onUpdate: BlockUpdateCallback;
+    /** Relay environment to use for the subscription */
+    relayEnvironment: IEnvironment;
+    /** The resource ID to subscribe to */
+    resourceId: ResourceId;
+}
+/**
+ * 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 declare function createRelayBlockSubscription(config: RelayBlockSubscriptionConfig): Unsubscribe;
+/**
+ * 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 declare function createRelaySubscriptionFunction(cloudId: string, relayEnvironment?: IEnvironment): (resourceId: ResourceId, onUpdate: BlockUpdateCallback, onError?: BlockSubscriptionErrorCallback) => Unsubscribe;

package/dist/types-ts4.5/utils/validValue.d.ts

@@ -1,3 +1,3 @@
-import type { SyncBlockProduct, SyncBlockStatus } from "../common/types";
+import type { SyncBlockProduct, SyncBlockStatus } from '../common/types';
 export declare const normaliseSyncBlockProduct: (value: string | null | undefined) => SyncBlockProduct | undefined;
 export declare const normaliseSyncBlockStatus: (value: string | null | undefined) => SyncBlockStatus | undefined;

package/package.json

@@ -34,10 +34,11 @@
 		"graphql-ws": "^5.14.2",
 		"lodash": "^4.17.21",
 		"raf-schd": "^4.0.3",
+		"relay-runtime": "npm:atl-relay-runtime@0.0.0-main-39e79f66",
 		"uuid": "^3.1.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^111.16.0",
+		"@atlaskit/editor-common": "^111.17.0",
 		"react": "^18.2.0"
 	},
 	"devDependencies": {
@@ -80,7 +81,7 @@
 		}
 	},
 	"name": "@atlaskit/editor-synced-block-provider",
-	"version": "3.30.2",
+	"version": "3.30.4",
 	"description": "Synced Block Provider for @atlaskit/editor-plugin-synced-block",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",