@atlaskit/media-client 36.3.1 → 36.3.3

package/AGENTS.md

@@ -0,0 +1,51 @@
+# media-client — Agent Guide
+
+> **Parent guide:** Always read [`../AGENTS.md`](../AGENTS.md) before working in this package — it
+> contains workspace-wide rules covering platform guidelines, changeset workflow, accessibility
+> standards, and the knowledge index protocol that applies to every Media package.
+
+## Package identity
+
+| Field | Value |
+|---|---|
+| NPM name | `@atlaskit/media-client` |
+| Path | `media-client/` |
+| Owner | Media Exif |
+| Purpose | Media API Web Client Library — manages file state subscriptions, uploads, downloads, and communication with the Media backend API |
+
+## Knowledge index
+
+> Read, search, edit, investigate, and validate the repository knowledge index at
+> `.agents/knowledge-index/`. ALWAYS use this skill before making ANY repo change, or when
+> exploring the codebase. The knowledge index is the canonical starting point for every coding task
+> in this repo, trigger this skill aggressively whenever the user mentions architecture, conventions,
+> packages, modules, services, build, coding, writing code, APIs, feature flags, testing, or
+> anything similar. Also trigger when "is the knowledge index up to date?" / "update the knowledge
+> index" / "what does the knowledge index say about Y?" — even if they don't say the words
+> "knowledge index". Also use it (via the `validate` subcommand) to detect drift between the
+> codebase and the docs after any code change. Use the `generate` subcommand to bootstrap the index
+> in a new repository.
+
+**Entry point:** `.agents/knowledge-index/INDEX.md`
+**Unit doc:** `.agents/knowledge-index/domains/media/units/atlaskit-media-client.md`
+**CLI:** `python3 .agents/skills/knowledge-index/scripts/kg.py {find,read,edit,investigate,validate,init,explore,generate} …`
+**Refresh protocol:** never silently bump `Last verified` — always re-read the listed `Sources` first, edit, then `kg.py edit <path> --message "<reason>"`.
+
+## Key source files
+
+- `src/index.ts` — public API entry point
+- `src/client/` — MediaClient implementation and file fetcher
+- `src/models/` — data models and error types
+- `src/uploader/` — file upload logic
+- `src/utils/` — utilities (hashing, polling, request, mobile upload state machine)
+- `src/upload-controller.ts` — upload lifecycle controller
+- `src/file-streams-cache.ts` — observable file state caching
+- `src/identifier.ts` — file/external identifier types
+
+## Development notes
+
+- Peer dependencies: `@atlaskit/media-core`, `@atlaskit/media-state`
+- Key internal dependencies: `@atlaskit/chunkinator`, `@atlaskit/media-common`
+- 8 feature flags registered (see `package.json` → `platform-feature-flags`)
+- Notable flags: `platform_media_cdn_delivery`, `platform_media_cdn_single_host`, `platform_media_auth_provider_analytics`
+- All new behaviour changes must be behind a feature gate (`fg()` from `@atlaskit/platform-feature-flags`)

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atlaskit/media-client
 
+## 36.3.3
+
+### Patch Changes
+
+- Updated dependencies
+
+## 36.3.2
+
+### Patch Changes
+
+- [`a68f551856a81`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/a68f551856a81) -
+  Add initialFileState to GetFileOptions interface to support SSR-seeded file state.
+- Updated dependencies
+
 ## 36.3.1
 
 ### Patch Changes

package/dist/cjs/client/file-fetcher/index.js

@@ -87,8 +87,8 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
       });
     });
     // TODO: ----- ADD TICKET TO PASS TRACE ID to this.dataloader.load
-    (0, _defineProperty2.default)(this, "createDownloadFileStream", function (id, collectionName, occurrenceKey, includeHashForDuplicateFiles, forceRefresh) {
-      var subject = (0, _createMediaSubject.createMediaSubject)();
+    (0, _defineProperty2.default)(this, "createDownloadFileStream", function (id, collectionName, occurrenceKey, includeHashForDuplicateFiles, forceRefresh, initialFileState) {
+      var subject = (0, _createMediaSubject.createMediaSubject)(initialFileState);
       var poll = new _polling.PollingFunction();
 
       // ensure subject errors if polling exceeds max iterations or uncaught exception in executor
@@ -100,6 +100,13 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
         return _regenerator.default.wrap(function (_context) {
           while (1) switch (_context.prev = _context.next) {
             case 0:
+              if (!(!forceRefresh && (initialFileState === null || initialFileState === void 0 ? void 0 : initialFileState.status) === 'processed')) {
+                _context.next = 1;
+                break;
+              }
+              subject.complete();
+              return _context.abrupt("return");
+            case 1:
               if (forceRefresh) {
                 _this.dataloader.clear({
                   id: id,
@@ -107,16 +114,16 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
                   includeHashForDuplicateFiles: includeHashForDuplicateFiles
                 });
               }
-              _context.next = 1;
+              _context.next = 2;
               return _this.dataloader.load({
                 id: id,
                 collectionName: collectionName,
                 includeHashForDuplicateFiles: includeHashForDuplicateFiles
               });
-            case 1:
+            case 2:
               response = _context.sent;
               if (!(0, _media.isNotFoundMediaItemDetails)(response)) {
-                _context.next = 2;
+                _context.next = 3;
                 break;
               }
               throw new _error.FileFetcherError('emptyItems', {
@@ -125,9 +132,9 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
                 occurrenceKey: occurrenceKey,
                 traceContext: response.metadataTraceContext
               });
-            case 2:
+            case 3:
               if (!(0, _detectEmptyFile.isEmptyFile)(response)) {
-                _context.next = 3;
+                _context.next = 4;
                 break;
               }
               throw new _error.FileFetcherError('zeroVersionFile', {
@@ -136,20 +143,20 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
                 occurrenceKey: occurrenceKey,
                 traceContext: response.metadataTraceContext
               });
-            case 3:
+            case 4:
               fileState = (0, _fileState2.mapMediaItemToFileState)(id, response);
               subject.next(fileState);
               _t = fileState.status;
-              _context.next = _t === 'processing' ? 4 : _t === 'processed' ? 5 : 6;
+              _context.next = _t === 'processing' ? 5 : _t === 'processed' ? 6 : 7;
               break;
-            case 4:
+            case 5:
               // the only case for continuing polling, otherwise this function is run once only
               poll.next();
-              return _context.abrupt("continue", 6);
-            case 5:
-              subject.complete();
-              return _context.abrupt("continue", 6);
+              return _context.abrupt("continue", 7);
             case 6:
+              subject.complete();
+              return _context.abrupt("continue", 7);
+            case 7:
             case "end":
               return _context.stop();
           }
@@ -464,8 +471,12 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
       var collectionName = options.collectionName,
         occurrenceKey = options.occurrenceKey,
         includeHashForDuplicateFiles = options.includeHashForDuplicateFiles,
-        forceRefresh = options.forceRefresh;
+        forceRefresh = options.forceRefresh,
+        initialFileState = options.initialFileState;
       if (!(0, _isValidUuid.isValidUuid)(id)) {
+        // Do NOT pass initialFileState here — for an invalid UUID the SSR seed
+        // is meaningless and would cause subscribers to briefly see a
+        // valid-looking file state before the error is emitted.
         var subject = (0, _createMediaSubject.createMediaSubject)();
         var err = new _error.FileFetcherError('invalidFileId', {
           id: id,
@@ -481,7 +492,7 @@ var FileFetcherImpl = exports.FileFetcherImpl = /*#__PURE__*/function () {
         (0, _fileStreamsCache.getFileStreamsCache)().remove(id);
       }
       return (0, _mediaSubscribable.fromObservable)((0, _fileStreamsCache.getFileStreamsCache)().getOrInsert(id, function () {
-        var subject = _this2.createDownloadFileStream(id, collectionName, undefined, includeHashForDuplicateFiles, forceRefresh);
+        var subject = _this2.createDownloadFileStream(id, collectionName, undefined, includeHashForDuplicateFiles, forceRefresh, initialFileState);
         subject.subscribe({
           next: function next(fileState) {
             _this2.setFileState(id, fileState);

package/dist/cjs/models/file-state.js

@@ -57,7 +57,8 @@ var mapMediaFileToFileState = exports.mapMediaFileToFileState = function mapMedi
     hash = _mediaFile$data.hash,
     abuseClassification = _mediaFile$data.abuseClassification,
     mediaMetadata = _mediaFile$data.mediaMetadata,
-    failReason = _mediaFile$data.failReason;
+    failReason = _mediaFile$data.failReason,
+    previewCdnUrl = _mediaFile$data.previewCdnUrl;
   var baseState = {
     id: id,
     name: name,
@@ -70,7 +71,8 @@ var mapMediaFileToFileState = exports.mapMediaFileToFileState = function mapMedi
     hash: hash,
     metadataTraceContext: metadataTraceContext,
     abuseClassification: abuseClassification,
-    mediaMetadata: mediaMetadata
+    mediaMetadata: mediaMetadata,
+    previewCdnUrl: previewCdnUrl
   };
   switch (processingStatus) {
     case 'pending':

package/dist/es2019/client/file-fetcher/index.js

@@ -57,13 +57,17 @@ export class FileFetcherImpl {
       });
     });
     // TODO: ----- ADD TICKET TO PASS TRACE ID to this.dataloader.load
-    _defineProperty(this, "createDownloadFileStream", (id, collectionName, occurrenceKey, includeHashForDuplicateFiles, forceRefresh) => {
-      const subject = createMediaSubject();
+    _defineProperty(this, "createDownloadFileStream", (id, collectionName, occurrenceKey, includeHashForDuplicateFiles, forceRefresh, initialFileState) => {
+      const subject = createMediaSubject(initialFileState);
       const poll = new PollingFunction();
 
       // ensure subject errors if polling exceeds max iterations or uncaught exception in executor
       poll.onError = error => subject.error(error);
       poll.execute(async () => {
+        if (!forceRefresh && (initialFileState === null || initialFileState === void 0 ? void 0 : initialFileState.status) === 'processed') {
+          subject.complete();
+          return;
+        }
         if (forceRefresh) {
           this.dataloader.clear({
             id,
@@ -275,9 +279,13 @@ export class FileFetcherImpl {
       collectionName,
       occurrenceKey,
       includeHashForDuplicateFiles,
-      forceRefresh
+      forceRefresh,
+      initialFileState
     } = options;
     if (!isValidUuid(id)) {
+      // Do NOT pass initialFileState here — for an invalid UUID the SSR seed
+      // is meaningless and would cause subscribers to briefly see a
+      // valid-looking file state before the error is emitted.
       const subject = createMediaSubject();
       const err = new FileFetcherError('invalidFileId', {
         id,
@@ -293,7 +301,7 @@ export class FileFetcherImpl {
       getFileStreamsCache().remove(id);
     }
     return fromObservable(getFileStreamsCache().getOrInsert(id, () => {
-      const subject = this.createDownloadFileStream(id, collectionName, undefined, includeHashForDuplicateFiles, forceRefresh);
+      const subject = this.createDownloadFileStream(id, collectionName, undefined, includeHashForDuplicateFiles, forceRefresh, initialFileState);
       subject.subscribe({
         next: fileState => {
           this.setFileState(id, fileState);

package/dist/es2019/models/file-state.js

@@ -31,7 +31,8 @@ export const mapMediaFileToFileState = mediaFile => {
     hash,
     abuseClassification,
     mediaMetadata,
-    failReason
+    failReason,
+    previewCdnUrl
   } = mediaFile.data;
   const baseState = {
     id,
@@ -45,7 +46,8 @@ export const mapMediaFileToFileState = mediaFile => {
     hash,
     metadataTraceContext,
     abuseClassification,
-    mediaMetadata
+    mediaMetadata,
+    previewCdnUrl
   };
   switch (processingStatus) {
     case 'pending':

package/dist/esm/client/file-fetcher/index.js

@@ -70,8 +70,8 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
       });
     });
     // TODO: ----- ADD TICKET TO PASS TRACE ID to this.dataloader.load
-    _defineProperty(this, "createDownloadFileStream", function (id, collectionName, occurrenceKey, includeHashForDuplicateFiles, forceRefresh) {
-      var subject = createMediaSubject();
+    _defineProperty(this, "createDownloadFileStream", function (id, collectionName, occurrenceKey, includeHashForDuplicateFiles, forceRefresh, initialFileState) {
+      var subject = createMediaSubject(initialFileState);
       var poll = new PollingFunction();
 
       // ensure subject errors if polling exceeds max iterations or uncaught exception in executor
@@ -83,6 +83,13 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
         return _regeneratorRuntime.wrap(function (_context) {
           while (1) switch (_context.prev = _context.next) {
             case 0:
+              if (!(!forceRefresh && (initialFileState === null || initialFileState === void 0 ? void 0 : initialFileState.status) === 'processed')) {
+                _context.next = 1;
+                break;
+              }
+              subject.complete();
+              return _context.abrupt("return");
+            case 1:
               if (forceRefresh) {
                 _this.dataloader.clear({
                   id: id,
@@ -90,16 +97,16 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
                   includeHashForDuplicateFiles: includeHashForDuplicateFiles
                 });
               }
-              _context.next = 1;
+              _context.next = 2;
               return _this.dataloader.load({
                 id: id,
                 collectionName: collectionName,
                 includeHashForDuplicateFiles: includeHashForDuplicateFiles
               });
-            case 1:
+            case 2:
               response = _context.sent;
               if (!isNotFoundMediaItemDetails(response)) {
-                _context.next = 2;
+                _context.next = 3;
                 break;
               }
               throw new FileFetcherError('emptyItems', {
@@ -108,9 +115,9 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
                 occurrenceKey: occurrenceKey,
                 traceContext: response.metadataTraceContext
               });
-            case 2:
+            case 3:
               if (!isEmptyFile(response)) {
-                _context.next = 3;
+                _context.next = 4;
                 break;
               }
               throw new FileFetcherError('zeroVersionFile', {
@@ -119,20 +126,20 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
                 occurrenceKey: occurrenceKey,
                 traceContext: response.metadataTraceContext
               });
-            case 3:
+            case 4:
               fileState = mapMediaItemToFileState(id, response);
               subject.next(fileState);
               _t = fileState.status;
-              _context.next = _t === 'processing' ? 4 : _t === 'processed' ? 5 : 6;
+              _context.next = _t === 'processing' ? 5 : _t === 'processed' ? 6 : 7;
               break;
-            case 4:
+            case 5:
               // the only case for continuing polling, otherwise this function is run once only
               poll.next();
-              return _context.abrupt("continue", 6);
-            case 5:
-              subject.complete();
-              return _context.abrupt("continue", 6);
+              return _context.abrupt("continue", 7);
             case 6:
+              subject.complete();
+              return _context.abrupt("continue", 7);
+            case 7:
             case "end":
               return _context.stop();
           }
@@ -447,8 +454,12 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
       var collectionName = options.collectionName,
         occurrenceKey = options.occurrenceKey,
         includeHashForDuplicateFiles = options.includeHashForDuplicateFiles,
-        forceRefresh = options.forceRefresh;
+        forceRefresh = options.forceRefresh,
+        initialFileState = options.initialFileState;
       if (!isValidUuid(id)) {
+        // Do NOT pass initialFileState here — for an invalid UUID the SSR seed
+        // is meaningless and would cause subscribers to briefly see a
+        // valid-looking file state before the error is emitted.
         var subject = createMediaSubject();
         var err = new FileFetcherError('invalidFileId', {
           id: id,
@@ -464,7 +475,7 @@ export var FileFetcherImpl = /*#__PURE__*/function () {
         getFileStreamsCache().remove(id);
       }
       return fromObservable(getFileStreamsCache().getOrInsert(id, function () {
-        var subject = _this2.createDownloadFileStream(id, collectionName, undefined, includeHashForDuplicateFiles, forceRefresh);
+        var subject = _this2.createDownloadFileStream(id, collectionName, undefined, includeHashForDuplicateFiles, forceRefresh, initialFileState);
         subject.subscribe({
           next: function next(fileState) {
             _this2.setFileState(id, fileState);

package/dist/esm/models/file-state.js

@@ -50,7 +50,8 @@ export var mapMediaFileToFileState = function mapMediaFileToFileState(mediaFile)
     hash = _mediaFile$data.hash,
     abuseClassification = _mediaFile$data.abuseClassification,
     mediaMetadata = _mediaFile$data.mediaMetadata,
-    failReason = _mediaFile$data.failReason;
+    failReason = _mediaFile$data.failReason,
+    previewCdnUrl = _mediaFile$data.previewCdnUrl;
   var baseState = {
     id: id,
     name: name,
@@ -63,7 +64,8 @@ export var mapMediaFileToFileState = function mapMediaFileToFileState(mediaFile)
     hash: hash,
     metadataTraceContext: metadataTraceContext,
     abuseClassification: abuseClassification,
-    mediaMetadata: mediaMetadata
+    mediaMetadata: mediaMetadata,
+    previewCdnUrl: previewCdnUrl
   };
   switch (processingStatus) {
     case 'pending':

package/dist/types/models/file-state.d.ts

@@ -6,6 +6,7 @@ export type FileStatus = CommonFileStatus;
 export interface PreviewOptions {
 }
 export interface GetFileOptions {
+    initialFileState?: FileState;
     preview?: PreviewOptions;
     collectionName?: string;
     occurrenceKey?: string;

package/dist/types/models/media.d.ts

@@ -25,6 +25,7 @@ export type MediaFile = {
     readonly abuseClassification?: AbuseClassification;
     readonly mediaMetadata?: FileMediaMetadata;
     readonly failReason?: ProcessingFailReason;
+    readonly previewCdnUrl?: string;
 };
 export type MediaItemDetails = {
     readonly mediaType: MediaType;
@@ -40,6 +41,7 @@ export type MediaItemDetails = {
     readonly abuseClassification?: AbuseClassification;
     readonly mediaMetadata?: FileMediaMetadata;
     readonly failReason?: ProcessingFailReason;
+    readonly previewCdnUrl?: string;
 };
 export type NotFoundMediaItemDetails = {
     readonly id: string;

package/dist/types-ts4.5/models/file-state.d.ts

@@ -6,6 +6,7 @@ export type FileStatus = CommonFileStatus;
 export interface PreviewOptions {
 }
 export interface GetFileOptions {
+    initialFileState?: FileState;
     preview?: PreviewOptions;
     collectionName?: string;
     occurrenceKey?: string;

package/dist/types-ts4.5/models/media.d.ts

@@ -25,6 +25,7 @@ export type MediaFile = {
     readonly abuseClassification?: AbuseClassification;
     readonly mediaMetadata?: FileMediaMetadata;
     readonly failReason?: ProcessingFailReason;
+    readonly previewCdnUrl?: string;
 };
 export type MediaItemDetails = {
     readonly mediaType: MediaType;
@@ -40,6 +41,7 @@ export type MediaItemDetails = {
     readonly abuseClassification?: AbuseClassification;
     readonly mediaMetadata?: FileMediaMetadata;
     readonly failReason?: ProcessingFailReason;
+    readonly previewCdnUrl?: string;
 };
 export type NotFoundMediaItemDetails = {
     readonly id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/media-client",
-	"version": "36.3.1",
+	"version": "36.3.3",
 	"description": "Media API Web Client Library",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -29,7 +29,7 @@
 		}
 	},
 	"dependencies": {
-		"@atlaskit/atlassian-context": "^0.9.0",
+		"@atlaskit/atlassian-context": "^0.10.0",
 		"@atlaskit/chunkinator": "^7.1.0",
 		"@atlaskit/media-common": "^13.3.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
@@ -46,13 +46,13 @@
 	},
 	"peerDependencies": {
 		"@atlaskit/media-core": "^37.1.0",
-		"@atlaskit/media-state": "^2.1.0"
+		"@atlaskit/media-state": "^2.2.0"
 	},
 	"devDependencies": {
 		"@atlaskit/media-core": "^37.1.0",
-		"@atlaskit/media-state": "^2.1.0",
+		"@atlaskit/media-state": "^2.2.0",
 		"@atlaskit/ssr": "workspace:^",
-		"@atlaskit/tokens": "^13.0.0",
+		"@atlaskit/tokens": "^13.1.0",
 		"@atlassian/a11y-jest-testing": "^0.11.0",
 		"@atlassian/feature-flags-test-utils": "^1.1.0",
 		"@emotion/react": "^11.7.1",