@protontech/drive-sdk 0.15.0 → 0.15.2

package/src/index.ts

@@ -10,7 +10,7 @@ export { OpenPGPCryptoWithCryptoProxy } from './crypto';
 export * from './errors';
 export { NullFeatureFlagProvider } from './featureFlags';
 export * from './interface';
-export type { EventSubscription } from './internal/events';
+export type { CoreApiEvent, EventSubscription } from './internal/events';
 export { ProtonDriveClient } from './protonDriveClient';
 export { VERSION } from './version';
 

package/src/internal/apiService/apiService.test.ts

@@ -223,6 +223,22 @@ describe('DriveAPIService', () => {
             expect(telemetry.recordMetric).not.toHaveBeenCalled();
         });
 
+        it('on transient socket / transport error', async () => {
+            const error = new Error('The socket connection was closed unexpectedly');
+            httpClient.fetchJson = jest
+                .fn()
+                .mockRejectedValueOnce(error)
+                .mockRejectedValueOnce(error)
+                .mockResolvedValueOnce(generateOkResponse());
+
+            const result = api.get('test');
+
+            await expect(result).resolves.toEqual({ Code: ErrorCode.OK });
+            expect(httpClient.fetchJson).toHaveBeenCalledTimes(3);
+            expectSDKEvents();
+            expect(telemetry.recordMetric).not.toHaveBeenCalled();
+        });
+
         it('on general error', async () => {
             const error = new Error('Error');
             httpClient.fetchJson = jest.fn().mockRejectedValueOnce(error).mockResolvedValueOnce(generateOkResponse());

package/src/internal/apiService/apiService.ts

@@ -3,6 +3,7 @@ import { c } from 'ttag';
 import { AbortError, ProtonDriveError, RateLimitedError, ServerError } from '../../errors';
 import { Logger, ProtonDriveHTTPClient, ProtonDriveTelemetry } from '../../interface';
 import { VERSION } from '../../version';
+import { isNetworkError } from '../errors';
 import { SDKEvents } from '../sdkEvents';
 import { waitSeconds } from '../wait';
 import { HTTPErrorCode, isCodeOk, isCodeOkAsync } from './errorCodes';
@@ -23,6 +24,11 @@ const DEFAULT_STORAGE_TIMEOUT_MS = 600_000;
  */
 const MAX_TIMEOUT_ERROR_RETRY_ATTEMPTS = 3;
 
+/**
+ * Maximum number of retry attempts for a network error.
+ */
+const MAX_NETWORK_ERROR_RETRY_ATTEMPTS = 3;
+
 /**
  * How many subsequent 429 errors are allowed before we stop further requests.
  */
@@ -55,6 +61,11 @@ const TOO_MANY_SUBSEQUENT_OFFLINE_ERRORS = 10;
  */
 const SERVER_ERROR_RETRY_DELAY_SECONDS = 1;
 
+/**
+ * After how long to re-try after network error.
+ */
+const NETWORK_ERROR_RETRY_DELAY_SECONDS = 5;
+
 /**
  * After how long to re-try after offline error.
  */
@@ -80,7 +91,7 @@ const GENERAL_RETRY_DELAY_SECONDS = 1;
  *
  * * exception from HTTP client
  *   * retry on offline exc. (with delay from OFFLINE_RETRY_DELAY_SECONDS)
- *   * retry on timeout exc. (with delay from SERVER_ERROR_RETRY_DELAY_SECONDS)
+ *   * retry on transient network exc. (with delay from SERVER_ERROR_RETRY_DELAY_SECONDS)
  *   * retry ONCE on any exc. (with delay from GENERAL_RETRY_DELAY_SECONDS)
  * * HTTP status 429
  *   * retry (with delay from `retry-after` header or DEFAULT_429_RETRY_DELAY_SECONDS)
@@ -318,6 +329,12 @@ export class DriveAPIService {
                     await waitSeconds(SERVER_ERROR_RETRY_DELAY_SECONDS);
                     return this.fetch(request, callback, { attempt: attempt + 1, previousError: error });
                 }
+
+                if (isNetworkError(error) && attempt + 1 < MAX_NETWORK_ERROR_RETRY_ATTEMPTS) {
+                    this.logger.warn(`${request.method} ${request.url}: Network error, retrying`);
+                    await waitSeconds(NETWORK_ERROR_RETRY_DELAY_SECONDS);
+                    return this.fetch(request, callback, { attempt: attempt + 1, previousError: error });
+                }
             }
             if (attempt === 0) {
                 this.logger.error(`${request.method} ${request.url}: failed, retrying once`, error);
@@ -367,7 +384,8 @@ export class DriveAPIService {
                     !(previousError instanceof Error) ||
                     (previousError instanceof Error &&
                         previousError.name !== 'TimeoutError' &&
-                        previousError.name !== 'OfflineError');
+                        previousError.name !== 'OfflineError' &&
+                        !isNetworkError(previousError));
 
                 if (isWarning) {
                     this.telemetry.recordMetric({

package/src/internal/errors.ts

@@ -72,7 +72,7 @@ export function isNetworkError(error: unknown): boolean {
     if (!(error instanceof Error)) {
         return false;
     }
-    return (
+    if (
         error.name === 'OfflineError' ||
         error.name === 'NetworkError' ||
         error.message?.toLowerCase() === 'network error' ||
@@ -80,5 +80,44 @@ export function isNetworkError(error: unknown): boolean {
             ['Failed to fetch', 'NetworkError when attempting to fetch resource', 'Load failed'].includes(
                 error.message,
             ))
+    ) {
+        return true;
+    }
+    if (errorMessageIndicatesTransientTransportFailure(error.message) || errorHasTransientTransportCode(error)) {
+        return true;
+    }
+    if (error.cause instanceof Error) {
+        return (
+            errorMessageIndicatesTransientTransportFailure(error.cause.message) ||
+            errorHasTransientTransportCode(error.cause)
+        );
+    }
+    return false;
+}
+
+function errorMessageIndicatesTransientTransportFailure(message: string | undefined): boolean {
+    if (!message) {
+        return false;
+    }
+    const lower = message.toLowerCase();
+    return (
+        // Remote end closed TLS/TCP without a complete response.
+        lower.includes('socket connection was closed unexpectedly') ||
+        // Remote end sent RST or closed the write side mid-request.
+        lower.includes('other side closed') ||
+        // Remote end closed the socket abruptly.
+        lower.includes('socket hang up')
+    );
+}
+
+function errorHasTransientTransportCode(error: Error): boolean {
+    const code = (error as NodeJS.ErrnoException).code;
+    return (
+        // TCP RST or equivalent: common under flaky networks or after server restart.
+        code === 'ECONNRESET' ||
+        // Writing to a socket whose other end is gone (often grouped with reset/hang-up).
+        code === 'EPIPE' ||
+        // Socket-level failure after connect (e.g. unexpected close on the wire).
+        code === 'UND_ERR_SOCKET'
     );
 }

package/src/internal/events/apiService.ts

@@ -4,7 +4,7 @@ import { DriveEvent, DriveEventsListWithStatus, DriveEventType, NodeEvent, NodeE
 
 type GetCoreLatestEventResponse =
     corePaths['/core/{_version}/events/latest']['get']['responses']['200']['content']['application/json'];
-type GetCoreEventResponse =
+export type CoreApiEvent =
     corePaths['/core/{_version}/events/{id}']['get']['responses']['200']['content']['application/json'];
 
 type GetVolumeLatestEventResponse =
@@ -40,28 +40,33 @@ export class EventsAPIService {
 
     async getCoreEvents(eventId: string): Promise<DriveEventsListWithStatus> {
         // TODO: Switch to v6 endpoint?
-        const result = await this.apiService.get<GetCoreEventResponse>(`core/v5/events/${eventId}`);
+        const result = await this.apiService.get<CoreApiEvent>(`core/v5/events/${eventId}`);
+        const driveEvents = EventsAPIService.getDriveEventsFromCoreEvent(result);
         // in core/v5/events, refresh is always all apps, value 255
         const refresh = result.Refresh > 0;
-        const events: DriveEvent[] =
-            refresh || result.DriveShareRefresh?.Action === 2
-                ? [
-                      {
-                          type: DriveEventType.SharedWithMeUpdated,
-                          eventId: result.EventID,
-                          treeEventScopeId: 'core',
-                      },
-                  ]
-                : [];
-
         return {
             latestEventId: result.EventID,
             more: result.More === 1,
             refresh,
-            events,
+            events: driveEvents,
         };
     }
 
+    static getDriveEventsFromCoreEvent(result: CoreApiEvent): DriveEvent[] {
+        // in core/v5/events, refresh is always all apps, value 255
+        const refresh = result.Refresh > 0;
+        if (refresh || result.DriveShareRefresh?.Action === 2) {
+            return [
+                {
+                    type: DriveEventType.SharedWithMeUpdated,
+                    eventId: result.EventID,
+                    treeEventScopeId: 'core',
+                },
+            ];
+        }
+        return [];
+    }
+
     async getVolumeLatestEventId(volumeId: string): Promise<string> {
         const result = await this.apiService.get<GetVolumeLatestEventResponse>(
             `drive/volumes/${volumeId}/events/latest`,
@@ -81,9 +86,7 @@ export class EventsAPIService {
                 const type = VOLUME_EVENT_TYPE_MAP[event.EventType];
                 const uids = {
                     nodeUid: makeNodeUid(volumeId, event.Link.LinkID),
-                    parentNodeUid: event.Link.ParentLinkID
-                        ? makeNodeUid(volumeId, event.Link.ParentLinkID)
-                        : undefined,
+                    parentNodeUid: event.Link.ParentLinkID ? makeNodeUid(volumeId, event.Link.ParentLinkID) : undefined,
                 };
                 return {
                     type,

package/src/internal/events/index.test.ts

@@ -0,0 +1,67 @@
+import { getMockTelemetry } from '../../tests/telemetry';
+import { DriveAPIService } from '../apiService';
+import { CoreApiEvent } from './apiService';
+import { DriveEventsService } from './index';
+import { DriveEventType, DriveListener } from './interface';
+
+describe('DriveEventsService', () => {
+    describe('processCoreEvent', () => {
+        function createService(cacheEventListeners: DriveListener[] = []) {
+            const telemetry = getMockTelemetry();
+            const apiService = {} as unknown as DriveAPIService;
+            const sharesService = { isOwnVolume: jest.fn() };
+            return new DriveEventsService(telemetry, apiService, sharesService, cacheEventListeners);
+        }
+
+        it('returns no drive events and does not notify listeners when the raw event is not a refresh', async () => {
+            const listener: jest.MockedFunction<DriveListener> = jest.fn().mockResolvedValue(undefined);
+            const service = createService([listener]);
+            const raw = {
+                EventID: 'event-no-refresh',
+                Refresh: 0,
+            } as CoreApiEvent;
+
+            const result = await service.processCoreEvent(raw);
+
+            expect(result).toEqual([]);
+            expect(listener).not.toHaveBeenCalled();
+        });
+
+        it('returns SharedWithMeUpdated when Refresh is non-zero', async () => {
+            const service = createService();
+            const raw = {
+                EventID: 'event-refresh',
+                Refresh: 255,
+            } as CoreApiEvent;
+
+            const result = await service.processCoreEvent(raw);
+
+            expect(result).toEqual([
+                {
+                    type: DriveEventType.SharedWithMeUpdated,
+                    eventId: 'event-refresh',
+                    treeEventScopeId: 'core',
+                },
+            ]);
+        });
+
+        it('returns SharedWithMeUpdated when DriveShareRefresh.Action is 2', async () => {
+            const service = createService();
+            const raw = {
+                EventID: 'event-share-refresh',
+                Refresh: 0,
+                DriveShareRefresh: { Action: 2 },
+            } as CoreApiEvent;
+
+            const result = await service.processCoreEvent(raw);
+
+            expect(result).toEqual([
+                {
+                    type: DriveEventType.SharedWithMeUpdated,
+                    eventId: 'event-share-refresh',
+                    treeEventScopeId: 'core',
+                },
+            ]);
+        });
+    });
+});

package/src/internal/events/index.ts

@@ -1,11 +1,12 @@
 import { Logger, ProtonDriveTelemetry } from '../../interface';
 import { DriveAPIService } from '../apiService';
-import { EventsAPIService } from './apiService';
+import { CoreApiEvent, EventsAPIService } from './apiService';
 import { CoreEventManager } from './coreEventManager';
 import { EventManager } from './eventManager';
 import { DriveEvent, DriveListener, EventSubscription, LatestEventIdProvider, SharesService } from './interface';
 import { VolumeEventManager } from './volumeEventManager';
 
+export type { CoreApiEvent } from './apiService';
 export type { DriveEvent, DriveListener, EventSubscription } from './interface';
 export { DriveEventType } from './interface';
 
@@ -37,7 +38,9 @@ export class DriveEventsService {
         this.volumeEventManagers = {};
     }
 
-    // FIXME: Allow to pass own core events manager from the public interface.
+    /**
+     * @deprecated Use `processCoreEvent` instead.
+     */
     async subscribeToCoreEvents(callback: DriveListener): Promise<EventSubscription> {
         let manager = this.coreEventManager;
         const started = !!manager;
@@ -72,6 +75,21 @@ export class DriveEventsService {
         return eventManager;
     }
 
+    /**
+     * Process a raw core API event fetched by the caller's own event loop.
+     * The SDK derives drive-relevant events from it, updates internal caches,
+     * and notifies all listeners registered via `subscribeToPushedCoreEvents`.
+     */
+    async processCoreEvent(rawEvent: CoreApiEvent): Promise<DriveEvent[]> {
+        const driveEvents = EventsAPIService.getDriveEventsFromCoreEvent(rawEvent);
+        for (const event of driveEvents) {
+            for (const listener of this.cacheEventListeners) {
+                await listener(event);
+            }
+        }
+        return driveEvents;
+    }
+
     /**
      * Subscribe to drive events. The treeEventScopeId can be obtained from a node.
      */

package/src/internal/nodes/cryptoService.ts

@@ -73,6 +73,8 @@ type NodesCryptoReporterNode = {
 export class NodesCryptoService {
     private logger: Logger;
 
+    protected allowContentKeyPacketFallbackVerification = true;
+
     constructor(
         telemetry: ProtonDriveTelemetry,
         protected driveCrypto: DriveCrypto,
@@ -541,6 +543,10 @@ export class NodesCryptoService {
             return result;
         }
 
+        if (!this.allowContentKeyPacketFallbackVerification) {
+            return result;
+        }
+
         const { volumeId: ownVolumeId } = await this.sharesService.getRootIDs();
         const { volumeId: nodesVolumeId } = splitNodeUid(node.uid);
 

package/src/internal/nodes/nodesAccess.test.ts

@@ -134,11 +134,11 @@ describe('nodesAccess', () => {
             const decryptedUnparsedNode = {
                 uid: 'volumeId~nodeId',
                 parentUid: 'volumeId~parentNodeid',
-                name: { ok: true, value: 'foo/bar' },
+                name: { ok: true, value: '' },
             } as DecryptedUnparsedNode;
             const decryptedNode = {
                 ...decryptedUnparsedNode,
-                name: { ok: false, error: { name: 'foo/bar', error: "Name must not contain the character '/'" } },
+                name: { ok: false, error: { name: '', error: "Name must not be empty" } },
                 treeEventScopeId: 'volumeId',
             } as DecryptedNode;
             const decryptedKeys = { key: 'key' } as any as DecryptedNodeKeys;

package/src/internal/nodes/nodesManagement.test.ts

@@ -426,7 +426,7 @@ describe('NodesManagement', () => {
     });
 
     it('copyNode throws error if name is invalid', async () => {
-        const promise = management.copyNode('nodeUid', 'newParentNodeUid', 'invalid/name');
+        const promise = management.copyNode('nodeUid', 'newParentNodeUid', '');
         await expect(promise).rejects.toThrow(ValidationError);
     });
 

package/src/internal/nodes/nodesManagement.ts

@@ -236,12 +236,12 @@ export abstract class NodesManagementBase<
     }
 
     async copyNode(nodeUid: string, newParentUid: string, name?: string): Promise<TDecryptedNode> {
-        if (name) {
+        if (name !== undefined) {
             validateNodeName(name);
         }
 
         const node = await this.nodesAccess.getNode(nodeUid);
-        const nodeName = name ? resultOk<string, Error | InvalidNameError>(name) : node.name;
+        const nodeName = name !== undefined ? resultOk<string, Error | InvalidNameError>(name) : node.name;
 
         const [keys, newParentKeys, signingKeys] = await Promise.all([
             this.nodesAccess.getNodePrivateAndSessionKeys(nodeUid),

package/src/internal/nodes/nodesRevisions.ts

@@ -14,7 +14,7 @@ export class NodesRevisons {
         private logger: Logger,
         private apiService: NodeAPIServiceBase,
         private cryptoService: NodesCryptoService,
-        private nodesAccess: Pick<NodesAccess, 'getNodeKeys'>,
+        private nodesAccess: Pick<NodesAccess, 'getNodeKeys' | 'notifyNodeChanged'>,
     ) {
         this.logger = logger;
         this.apiService = apiService;
@@ -67,6 +67,10 @@ export class NodesRevisons {
 
     async restoreRevision(nodeRevisionUid: string): Promise<void> {
         await this.apiService.restoreRevision(nodeRevisionUid);
+
+        // Restoring a revision creates a new active revision.
+        const nodeUid = makeNodeUidFromRevisionUid(nodeRevisionUid);
+        await this.nodesAccess.notifyNodeChanged(nodeUid);
     }
 
     async deleteRevision(nodeRevisionUid: string): Promise<void> {

package/src/internal/nodes/validations.ts

@@ -5,7 +5,7 @@ import { ValidationError } from '../../errors';
 const MAX_NODE_NAME_LENGTH = 255;
 
 /**
- * @throws Error if the name is empty, long, or includes slash in the name.
+ * @throws Error if the name is empty or long.
  */
 export function validateNodeName(name: string): void {
     if (!name) {
@@ -20,7 +20,4 @@ export function validateNodeName(name: string): void {
             ),
         );
     }
-    if (name.includes('/')) {
-        throw new ValidationError(c('Error').t`Name must not contain the character '/'`);
-    }
 }

package/src/internal/photos/addToAlbum.test.ts

@@ -69,7 +69,7 @@ describe('AddToAlbumProcess', () => {
         // @ts-expect-error Mocking for testing purposes
         apiService = {
             addPhotosToAlbum: jest.fn(),
-            copyPhotoToAlbum: jest.fn(),
+            copyPhoto: jest.fn(),
         };
 
         // @ts-expect-error Mocking for testing purposes
@@ -154,7 +154,7 @@ describe('AddToAlbumProcess', () => {
         });
 
         let copyToAlbumReturnedMissing = false;
-        apiService.copyPhotoToAlbum.mockImplementation(async (albumUid, payload) => {
+        apiService.copyPhoto.mockImplementation(async (albumUid, payload) => {
             let error: Error | undefined;
             if (payload.nodeUid.includes('missingRelatedTwice')) {
                 error = new MissingRelatedPhotosError(['volume2~missingRelatedTwice1']);
@@ -322,7 +322,7 @@ describe('AddToAlbumProcess', () => {
             const photoUids = Array.from({ length: 25 }, (_, i) => `volume2~photo${i}`);
 
             let copyPhotoCallCount = 0;
-            apiService.copyPhotoToAlbum.mockImplementation(async (albumUid, payload) => {
+            apiService.copyPhoto.mockImplementation(async (albumUid, payload) => {
                 copyPhotoCallCount++;
 
                 // First few calls should happen before all 25 photos are prepared
@@ -351,8 +351,8 @@ describe('AddToAlbumProcess', () => {
                 uid: mainPhotoUid,
                 ok: true,
             }])
-            expect(apiService.copyPhotoToAlbum).toHaveBeenCalledTimes(1);
-            const params = apiService.copyPhotoToAlbum.mock.calls[0];
+            expect(apiService.copyPhoto).toHaveBeenCalledTimes(1);
+            const params = apiService.copyPhoto.mock.calls[0];
             expect(params[1].relatedPhotos?.length).toBe(15);
         });
 
@@ -366,7 +366,7 @@ describe('AddToAlbumProcess', () => {
                 ok: true,
             }]);
             expect(nodesService.iterateNodes).toHaveBeenCalledTimes(3); // main photo + related photo + missing related photo
-            expect(apiService.copyPhotoToAlbum).toHaveBeenCalledTimes(2); // two attempts
+            expect(apiService.copyPhoto).toHaveBeenCalledTimes(2); // two attempts
         });
 
         it('should return error if missing related photos error occurs twice', async () => {
@@ -380,7 +380,7 @@ describe('AddToAlbumProcess', () => {
                 error: new MissingRelatedPhotosError(['volume2~missingRelatedOnce1']),
             }]);
             expect(nodesService.iterateNodes).toHaveBeenCalledTimes(3); // main photo + related photo + missing related photo
-            expect(apiService.copyPhotoToAlbum).toHaveBeenCalledTimes(2); // two attempts
+            expect(apiService.copyPhoto).toHaveBeenCalledTimes(2); // two attempts
         });
 
         it('should return error when crypto service fails', async () => {
@@ -428,7 +428,7 @@ describe('AddToAlbumProcess', () => {
         it('should not notify for failed photo copies', async () => {
             const photoUid = 'volume2~photo1';
 
-            apiService.copyPhotoToAlbum.mockRejectedValue(new Error('API error'));
+            apiService.copyPhoto.mockRejectedValue(new Error('API error'));
 
             const results = await executeProcess([photoUid]);
 
@@ -467,9 +467,9 @@ describe('AddToAlbumProcess', () => {
             expect(nodesService.iterateNodes.mock.calls[1][0]).toMatchObject(differentVolumeUids);
             expect(apiService.addPhotosToAlbum).toHaveBeenCalledTimes(1);
             expect(apiService.addPhotosToAlbum.mock.calls[0][1].map(({ nodeUid }) => nodeUid)).toMatchObject(sameVolumeUids);
-            expect(apiService.copyPhotoToAlbum).toHaveBeenCalledTimes(2);
-            expect(apiService.copyPhotoToAlbum.mock.calls[0][1].nodeUid).toBe(differentVolumeUids[0]);
-            expect(apiService.copyPhotoToAlbum.mock.calls[1][1].nodeUid).toBe(differentVolumeUids[1]);
+            expect(apiService.copyPhoto).toHaveBeenCalledTimes(2);
+            expect(apiService.copyPhoto.mock.calls[0][1].nodeUid).toBe(differentVolumeUids[0]);
+            expect(apiService.copyPhoto.mock.calls[1][1].nodeUid).toBe(differentVolumeUids[1]);
         });
 
         it('should prepare payloads in parallel for both queues', async () => {
@@ -496,7 +496,7 @@ describe('AddToAlbumProcess', () => {
             expect(results[1].ok).toBe(true);
             expect(nodesService.iterateNodes).toHaveBeenCalledTimes(3 + 3); // main photo + related photo + missing related photo
             expect(apiService.addPhotosToAlbum).toHaveBeenCalledTimes(2); // two attempts
-            expect(apiService.copyPhotoToAlbum).toHaveBeenCalledTimes(2); // two attempts
+            expect(apiService.copyPhoto).toHaveBeenCalledTimes(2); // two attempts
         });
 
         it('should notify correctly for both volumes', async () => {

package/src/internal/photos/addToAlbum.ts

@@ -118,7 +118,7 @@ export class AddToAlbumProcess {
 
             for (const payload of payloads) {
                 try {
-                    const newPhotoNodeUid = await this.apiService.copyPhotoToAlbum(
+                    const newPhotoNodeUid = await this.apiService.copyPhoto(
                         this.albumNodeUid,
                         payload,
                         this.signal,

package/src/internal/photos/albumsManager.test.ts

@@ -152,7 +152,7 @@ describe('Albums', () => {
         });
 
         it('throws validation error for invalid album name', async () => {
-            await expect(albums.createAlbum('invalid/name')).rejects.toThrow(ValidationError);
+            await expect(albums.createAlbum('')).rejects.toThrow(ValidationError);
         });
 
         it('throws error when parent hash key is not available', async () => {
@@ -228,7 +228,7 @@ describe('Albums', () => {
         });
 
         it('throws validation error for invalid album name', async () => {
-            await expect(albums.updateAlbum('albumNodeUid', { name: 'invalid/name' })).rejects.toThrow(ValidationError);
+            await expect(albums.updateAlbum('albumNodeUid', { name: '' })).rejects.toThrow(ValidationError);
         });
     });
 

package/src/internal/photos/albumsManager.ts

@@ -133,7 +133,7 @@ export class AlbumsManager {
             coverPhotoNodeUid?: string;
         },
     ): Promise<DecryptedPhotoNode> {
-        if (updates.name) {
+        if (updates.name !== undefined) {
             validateNodeName(updates.name);
         }
 

package/src/internal/photos/apiService.test.ts

@@ -147,7 +147,7 @@ describe('photosAPIService', () => {
         });
     });
 
-    describe('copyPhotoToAlbum', () => {
+    describe('copyPhoto', () => {
         const photoPayloads = [
             {
                 nodeUid: 'volumeId2~photoNodeId1',
@@ -181,7 +181,7 @@ describe('photosAPIService', () => {
                 LinkID: 'photoNodeId1',
             });
 
-            const result = await api.copyPhotoToAlbum(albumNodeUid, photoPayloads[0]);
+            const result = await api.copyPhoto(albumNodeUid, photoPayloads[0]);
 
             expect(result).toEqual('volumeId1~photoNodeId1');
             expect(apiMock.post).toHaveBeenCalledWith(
@@ -215,7 +215,7 @@ describe('photosAPIService', () => {
                 },
             ));
 
-            const promise = api.copyPhotoToAlbum(albumNodeUid, photoPayloads[0]);
+            const promise = api.copyPhoto(albumNodeUid, photoPayloads[0]);
 
             await expect(promise).rejects.toThrow(MissingRelatedPhotosError);
             try {
@@ -229,7 +229,7 @@ describe('photosAPIService', () => {
             const error = new APICodeError('Some error', 3000);
             apiMock.post = jest.fn().mockRejectedValue(error);
 
-            const promise = api.copyPhotoToAlbum(albumNodeUid, photoPayloads[0]);
+            const promise = api.copyPhoto(albumNodeUid, photoPayloads[0]);
 
             await expect(promise).rejects.toThrow(error);
         });

package/src/internal/photos/apiService.ts

@@ -358,7 +358,7 @@ export class PhotosAPIService {
     /**
      * Add photos from the same volume to an album.
      *
-     * To add photos from different volumes, use the {@link copyPhotoToAlbum} method.
+     * To add photos from different volumes, use the {@link copyPhoto} method.
      *
      * In the future, these two methods will be merged into a single one.
      */
@@ -432,26 +432,26 @@ export class PhotosAPIService {
     }
 
     /**
-     * Copy a photo to a shared album on a different volume.
+     * Copy a photo from a different volume to an album or to the user's own timeline root.
      *
      * To add photos from the same volume to an album, use the {@link addPhotosToAlbum} method.
      *
      * In the future, these two methods will be merged into a single one.
      */
-    async copyPhotoToAlbum(
-        albumNodeUid: string,
+    async copyPhoto(
+        targetNodeUid: string,
         payload: TransferEncryptedPhotoPayload,
         signal?: AbortSignal,
     ): Promise<string> {
         const { volumeId: sourceVolumeId, nodeId: sourceLinkId } = splitNodeUid(payload.nodeUid);
-        const { volumeId: targetVolumeId, nodeId: targetAlbumLinkId } = splitNodeUid(albumNodeUid);
+        const { volumeId: targetVolumeId, nodeId: targetNodeId } = splitNodeUid(targetNodeUid);
 
         try {
             const response = await this.apiService.post<PostCopyLinkRequest, PostCopyLinkResponse>(
                 `drive/volumes/${sourceVolumeId}/links/${sourceLinkId}/copy`,
                 {
                     TargetVolumeID: targetVolumeId,
-                    TargetParentLinkID: targetAlbumLinkId,
+                    TargetParentLinkID: targetNodeId,
                     Hash: payload.nameHash,
                     Name: payload.encryptedName,
                     NameSignatureEmail: payload.nameSignatureEmail,