@atlaskit/editor-synced-block-provider 4.1.2 → 4.1.4

package/AGENTS.md

@@ -0,0 +1,117 @@
+# Synced Block Provider — Developer Agent Guide
+
+> **Package**: `@atlaskit/editor-synced-block-provider`
+> **Purpose**: Data layer for synced blocks — store managers, block service API client, ARI generation, permissions, media tokens.
+> **Full Knowledge Base**: [Synced Blocks — Comprehensive Knowledge Base](https://hello.atlassian.net/wiki/spaces/egcuc/pages/6679548384)
+
+---
+
+## Quick Context
+
+This package manages the lifecycle and state of synced blocks for both source and reference nodes.
+It provides the data fetching, caching, subscription, and persistence layer used by the editor plugin
+and the renderer across Confluence and Jira.
+
+---
+
+## Source Structure
+
+```
+src/
+├── index.ts                          ← Barrel export
+├── store-manager/
+│   ├── syncBlockStoreManager.ts      ← Parent coordinator for source + reference managers
+│   ├── referenceSyncBlockStoreManager.ts ← Reference block lifecycle, cache, subscriptions, flush
+│   └── sourceSyncBlockStoreManager.ts    ← Source block create, update, delete, flush
+├── clients/
+│   ├── block-service/
+│   │   ├── blockService.ts           ← Block service API client (fetch, batch, CRUD)
+│   │   └── ari.ts                    ← Block ARI generation/parsing
+│   ├── confluence/
+│   │   ├── ari.ts                    ← Confluence page ARI generation/parsing
+│   │   └── fetchMediaToken.ts        ← Media token fetching via GraphQL (MediaUploadTokenQuery)
+│   └── jira/
+│       └── ari.ts                    ← Jira work item ARI generation/parsing
+├── providers/
+│   └── block-service/
+│       └── blockServiceAPI.ts        ← Provider factory and API helpers
+└── types/                            ← Shared types
+```
+
+---
+
+## Key Concepts
+
+### Store Manager Hierarchy
+
+```
+SyncBlockStoreManager (parent coordinator)
+├── SourceSyncBlockStoreManager
+│   ├── create(content) → Block Service API → returns resourceId
+│   ├── update(resourceId, content) → debounced 3s write
+│   ├── delete(resourceId) → soft delete
+│   └── flush() → persist all pending changes on page save
+└── ReferenceSyncBlockStoreManager
+    ├── fetchSyncBlocksData(nodes) → batch fetch with deduplication
+    ├── subscribeToSyncBlock(resourceId, localId, callback) → AGG WebSocket
+    ├── fetchSyncBlockSourceInfo(resourceId) → title, URL metadata
+    ├── getFromCache(resourceId) → retrieve cached data
+    ├── flush() → save reference changes to backend
+    └── destroy() → cleanup subscriptions and batchers
+```
+
+### ARI Formats & Utilities
+
+| Function | ARI Pattern | Example |
+|----------|-------------|---------|
+| `generateBlockAri({cloudId, parentId, product, resourceId})` | Source block ARI | `ari:cloud:block::{cloudId}/confluence-page:{pageId}/{localId}` |
+| `generateBlockAriFromReference({cloudId, resourceId})` | Reference block ARI | — |
+| `getConfluencePageAri({pageId, cloudId, pageType})` | Confluence page | `ari:cloud:confluence::{cloudId}:page/{pageId}` |
+| `getJiraWorkItemAri({cloudId, workItemId})` | Jira issue | `ari:cloud:jira::{cloudId}:work-item/{issueId}` |
+| `getJiraWorkItemIdFromAri(ari)` | Extract issue ID from ARI | — |
+
+### Block Service API
+
+The client in `clients/block-service/blockService.ts` communicates via GraphQL at `/gateway/api/graphql`:
+- **Fetch**: Single or batch block content retrieval
+- **Create**: Register new source block with content
+- **Update**: Push content changes (debounced 3s)
+- **Delete**: Soft delete a source block
+- **Source Info**: Fetch metadata (source page title, URL)
+- **References Info**: Fetch list of locations referencing a block
+
+### Media Token Fetching
+
+`fetchMediaToken(contentId)` → GraphQL `MediaUploadTokenQuery` → returns `{token, config: {clientId, fileStoreUrl}, collectionId}`
+
+Used when synced blocks contain media (images, files) — the reference needs a valid token to render media from the source page.
+
+---
+
+## Common Tasks
+
+### Adding a new API method
+1. Add the GraphQL query/mutation in `clients/block-service/blockService.ts`
+2. Expose it through the appropriate store manager
+3. Export from `src/index.ts` if needed by product integrations
+4. Add tests in `editor-synced-block-provider-tests`
+
+### Debugging data issues
+1. Check `ReferenceSyncBlockStoreManager` cache state
+2. Verify ARI format matches expected pattern for the product
+3. Check Block Service API responses in network tab (look for `/gateway/api/graphql`)
+4. Use analytics: [HOW-TO: Debug errors](https://hello.atlassian.net/wiki/spaces/egcuc/pages/6342760320)
+
+### Adding support for a new product
+1. Create ARI utilities in `clients/{product}/ari.ts`
+2. Ensure `generateBlockAri` supports the new product type
+3. Add media token fetching if the product has media content
+4. Update store managers if the product has unique lifecycle requirements
+
+---
+
+## Related Packages
+- **Plugin**: `platform/packages/editor/editor-plugin-synced-block/` — uses store managers
+- **Renderer**: `platform/packages/editor/editor-synced-block-renderer/` — uses fetch provider
+- **Confluence**: `confluence/next/packages/fabric-providers/src/SyncedBlockProvider.ts` — wraps this provider
+- **Jira**: `jira/src/packages/issue/issue-view-synced-block-provider/` — wraps this provider with Relay

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @atlaskit/editor-synced-block-provider
 
+## 4.1.4
+
+### Patch Changes
+
+- Updated dependencies
+
+## 4.1.3
+
+### Patch Changes
+
+- [`3895f6d32cc49`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/3895f6d32cc49) -
+  Set hasReceivedContentChange on successful sync block creation to ensure unsaved changes are
+  flushed
+- Updated dependencies
+
 ## 4.1.2
 
 ### Patch Changes

package/dist/cjs/store-manager/sourceSyncBlockStoreManager.js

@@ -12,6 +12,7 @@ var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/creat
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _isEqual = _interopRequireDefault(require("lodash/isEqual"));
 var _monitoring = require("@atlaskit/editor-common/monitoring");
+var _experiments = require("@atlaskit/tmp-editor-statsig/experiments");
 var _types = require("../common/types");
 var _errorHandling = require("../utils/errorHandling");
 var _experienceTracking = require("../utils/experienceTracking");
@@ -227,6 +228,13 @@ var SourceSyncBlockStoreManager = exports.SourceSyncBlockStoreManager = /*#__PUR
       if (onCompletion) {
         this.creationCompletionCallbacks.delete(resourceId);
         onCompletion(success);
+        if (success && (0, _experiments.editorExperiment)('platform_synced_block_patch_6', true, {
+          exposure: true
+        })) {
+          // If creation is successful, set hasReceivedContentChange to true
+          // to indicate that there are unsaved changes in the cache
+          this.hasReceivedContentChange = true;
+        }
       } else {
         var _this$fireAnalyticsEv3;
         (_this$fireAnalyticsEv3 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv3 === void 0 || _this$fireAnalyticsEv3.call(this, (0, _errorHandling.createErrorPayload)('creation complete callback missing', resourceId));

package/dist/es2019/store-manager/sourceSyncBlockStoreManager.js

@@ -1,6 +1,7 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import isEqual from 'lodash/isEqual';
 import { logException } from '@atlaskit/editor-common/monitoring';
+import { editorExperiment } from '@atlaskit/tmp-editor-statsig/experiments';
 import { SyncBlockError } from '../common/types';
 import { updateErrorPayload, createErrorPayload, deleteErrorPayload, updateCacheErrorPayload, getSourceInfoErrorPayload, updateSuccessPayload, createSuccessPayload, deleteSuccessPayload, fetchReferencesErrorPayload } from '../utils/errorHandling';
 import { getCreateSourceExperience, getDeleteSourceExperience, getSaveSourceExperience, getFetchSourceInfoExperience } from '../utils/experienceTracking';
@@ -168,6 +169,13 @@ export class SourceSyncBlockStoreManager {
     if (onCompletion) {
       this.creationCompletionCallbacks.delete(resourceId);
       onCompletion(success);
+      if (success && editorExperiment('platform_synced_block_patch_6', true, {
+        exposure: true
+      })) {
+        // If creation is successful, set hasReceivedContentChange to true
+        // to indicate that there are unsaved changes in the cache
+        this.hasReceivedContentChange = true;
+      }
     } else {
       var _this$fireAnalyticsEv5;
       (_this$fireAnalyticsEv5 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv5 === void 0 ? void 0 : _this$fireAnalyticsEv5.call(this, createErrorPayload('creation complete callback missing', resourceId));

package/dist/esm/store-manager/sourceSyncBlockStoreManager.js

@@ -7,6 +7,7 @@ function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbol
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 import isEqual from 'lodash/isEqual';
 import { logException } from '@atlaskit/editor-common/monitoring';
+import { editorExperiment } from '@atlaskit/tmp-editor-statsig/experiments';
 import { SyncBlockError } from '../common/types';
 import { updateErrorPayload, createErrorPayload, deleteErrorPayload, updateCacheErrorPayload, getSourceInfoErrorPayload, updateSuccessPayload, createSuccessPayload, deleteSuccessPayload, fetchReferencesErrorPayload } from '../utils/errorHandling';
 import { getCreateSourceExperience, getDeleteSourceExperience, getSaveSourceExperience, getFetchSourceInfoExperience } from '../utils/experienceTracking';
@@ -220,6 +221,13 @@ export var SourceSyncBlockStoreManager = /*#__PURE__*/function () {
       if (onCompletion) {
         this.creationCompletionCallbacks.delete(resourceId);
         onCompletion(success);
+        if (success && editorExperiment('platform_synced_block_patch_6', true, {
+          exposure: true
+        })) {
+          // If creation is successful, set hasReceivedContentChange to true
+          // to indicate that there are unsaved changes in the cache
+          this.hasReceivedContentChange = true;
+        }
       } else {
         var _this$fireAnalyticsEv3;
         (_this$fireAnalyticsEv3 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv3 === void 0 || _this$fireAnalyticsEv3.call(this, createErrorPayload('creation complete callback missing', resourceId));

package/package.json

@@ -29,7 +29,7 @@
 		"@atlaskit/editor-prosemirror": "^7.3.0",
 		"@atlaskit/node-data-provider": "^9.0.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
-		"@atlaskit/tmp-editor-statsig": "^41.0.0",
+		"@atlaskit/tmp-editor-statsig": "^43.0.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"graphql-ws": "^5.14.2",
@@ -38,7 +38,7 @@
 		"uuid": "^3.1.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^112.6.0",
+		"@atlaskit/editor-common": "^112.7.0",
 		"react": "^18.2.0"
 	},
 	"devDependencies": {
@@ -81,7 +81,7 @@
 		}
 	},
 	"name": "@atlaskit/editor-synced-block-provider",
-	"version": "4.1.2",
+	"version": "4.1.4",
 	"description": "Synced Block Provider for @atlaskit/editor-plugin-synced-block",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",