@protontech/drive-sdk 0.9.8 → 0.10.0

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

@@ -0,0 +1,233 @@
+import { DriveAPIService } from '../apiService/apiService';
+import { APICodeError, InvalidRequirementsAPIError } from '../apiService/errors';
+import { PhotosAPIService } from './apiService';
+import { MissingRelatedPhotosError } from './errors';
+
+describe('photosAPIService', () => {
+    let apiMock: DriveAPIService;
+    let api: PhotosAPIService;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+
+        // @ts-expect-error Mocking for testing purposes
+        apiMock = {
+            get: jest.fn(),
+            post: jest.fn(),
+            put: jest.fn(),
+        };
+
+        api = new PhotosAPIService(apiMock);
+    });
+
+    const albumNodeUid = 'volumeId1~albumNodeId';
+
+    describe('addPhotosToAlbum', () => {
+        const photoPayloads = [
+            {
+                nodeUid: 'volumeId1~photoNodeId1',
+                contentHash: 'contentHash1',
+                nameHash: 'nameHash1',
+                encryptedName: 'encryptedName1',
+                nameSignatureEmail: 'nameSignatureEmail1',
+                nodePassphrase: 'nodePassphrase1',
+                nodePassphraseSignature: 'nodePassphraseSignature1',
+                signatureEmail: 'signatureEmail1',
+                relatedPhotos: [
+                    {
+                        nodeUid: 'volumeId1~photoNodeId2',
+                        contentHash: 'contentHash2',
+                        nameHash: 'nameHash2',
+                        encryptedName: 'encryptedName2',
+                        nameSignatureEmail: 'nameSignatureEmail2',
+                        nodePassphrase: 'nodePassphrase2',
+                        nodePassphraseSignature: 'nodePassphraseSignature2',
+                        signatureEmail: 'signatureEmail2',
+                    },
+                ],
+            },
+        ];
+
+        it('should add photos to album', async () => {
+            apiMock.post = jest.fn().mockResolvedValue({
+                Code: 1000,
+                Responses: [
+                    {
+                        LinkID: 'photoNodeId1',
+                        Response: {
+                            Code: 1000,
+                        },
+                    },
+                ],
+            });
+
+            const result = await Array.fromAsync(api.addPhotosToAlbum(albumNodeUid, photoPayloads));
+
+            expect(result).toEqual([
+                {
+                    uid: 'volumeId1~photoNodeId1',
+                    ok: true,
+                },
+            ]);
+            expect(apiMock.post).toHaveBeenCalledWith(
+                `drive/photos/volumes/volumeId1/albums/albumNodeId/add-multiple`,
+                {
+                    AlbumData: [
+                        expect.objectContaining({
+                            LinkID: 'photoNodeId1',
+                            Hash: 'nameHash1',
+                            Name: 'encryptedName1',
+                            NameSignatureEmail: 'nameSignatureEmail1',
+                        }),
+                        expect.objectContaining({
+                            LinkID: 'photoNodeId2',
+                            Hash: 'nameHash2',
+                            Name: 'encryptedName2',
+                            NameSignatureEmail: 'nameSignatureEmail2',
+                        }),
+                    ],
+                },
+                undefined,
+            );
+        });
+
+        it('should return MissingRelatedPhotosError if related photos are missing', async () => {
+            apiMock.post = jest.fn().mockResolvedValue({
+                Code: 1000,
+                Responses: [
+                    {
+                        LinkID: 'photoNodeId1',
+                        Response: {
+                            Code: 2000,
+                            Details: {
+                                Missing: ['photoNodeId3'],
+                            },
+                        },
+                    },
+                ],
+            });
+
+            const result = await Array.fromAsync(api.addPhotosToAlbum(albumNodeUid, photoPayloads));
+
+            expect(result).toEqual([
+                {
+                    uid: 'volumeId1~photoNodeId1',
+                    ok: false,
+                    error: new MissingRelatedPhotosError([]),
+                },
+            ]);
+            expect((result[0] as any).error.missingNodeUids).toEqual(['volumeId1~photoNodeId3']);
+        });
+
+        it('should return error for unknown error', async () => {
+            apiMock.post = jest.fn().mockResolvedValue({
+                Code: 1000,
+                Responses: [
+                    {
+                        LinkID: 'photoNodeId1',
+                        Response: {
+                            Code: 3000,
+                            Error: 'Some error',
+                        },
+                    },
+                ],
+            });
+
+            const result = await Array.fromAsync(api.addPhotosToAlbum(albumNodeUid, photoPayloads));
+
+            expect(result).toEqual([
+                {
+                    uid: 'volumeId1~photoNodeId1',
+                    ok: false,
+                    error: new APICodeError('Some error', 3000),
+                },
+            ]);
+        });
+    });
+
+    describe('copyPhotoToAlbum', () => {
+        const photoPayloads = [
+            {
+                nodeUid: 'volumeId2~photoNodeId1',
+                contentHash: 'contentHash1',
+                nameHash: 'nameHash1',
+                encryptedName: 'encryptedName1',
+                nameSignatureEmail: 'nameSignatureEmail1',
+                nodePassphrase: 'nodePassphrase1',
+                nodePassphraseSignature: 'nodePassphraseSignature1',
+                signatureEmail: 'signatureEmail1',
+                relatedPhotos: [
+                    {
+                        nodeUid: 'volumeId2~photoNodeId2',
+                        contentHash: 'contentHash2',
+                        nameHash: 'nameHash2',
+                        encryptedName: 'encryptedName2',
+                        nameSignatureEmail: 'nameSignatureEmail2',
+                        nodePassphrase: 'nodePassphrase2',
+                        nodePassphraseSignature: 'nodePassphraseSignature2',
+                        signatureEmail: 'signatureEmail2',
+                    },
+                ],
+            },
+        ];
+
+        it('should copy photo to album', async () => {
+            apiMock.post = jest.fn().mockResolvedValue({
+                Code: 1000,
+                LinkID: 'photoNodeId1',
+            });
+
+            const result = await api.copyPhotoToAlbum(albumNodeUid, photoPayloads[0]);
+
+            expect(result).toEqual('volumeId1~photoNodeId1');
+            expect(apiMock.post).toHaveBeenCalledWith(
+                `drive/volumes/volumeId2/links/photoNodeId1/copy`,
+                expect.objectContaining({
+                    TargetVolumeID: 'volumeId1',
+                    TargetParentLinkID: 'albumNodeId',
+                    Hash: 'nameHash1',
+                    Name: 'encryptedName1',
+                    Photos: {
+                        ContentHash: 'contentHash1',
+                        RelatedPhotos: expect.arrayContaining([
+                            expect.objectContaining({
+                                LinkID: 'photoNodeId2',
+                                Hash: 'nameHash2',
+                                Name: 'encryptedName2',
+                            }),
+                        ]),
+                    },
+                }),
+                undefined,
+            );
+        });
+
+        it('should return MissingRelatedPhotosError if related photos are missing', async () => {
+            apiMock.post = jest.fn().mockRejectedValue(new InvalidRequirementsAPIError(
+                'Missing related photos',
+                2000,
+                {
+                    Missing: ['photoNodeId3'],
+                },
+            ));
+
+            const promise = api.copyPhotoToAlbum(albumNodeUid, photoPayloads[0]);
+
+            await expect(promise).rejects.toThrow(MissingRelatedPhotosError);
+            try {
+                await promise;
+            } catch (error) {
+                expect((error as MissingRelatedPhotosError).missingNodeUids).toEqual(['volumeId2~photoNodeId3']);
+            }
+        });
+
+        it('should return error for unknown error', async () => {
+            const error = new APICodeError('Some error', 3000);
+            apiMock.post = jest.fn().mockRejectedValue(error);
+
+            const promise = api.copyPhotoToAlbum(albumNodeUid, photoPayloads[0]);
+
+            await expect(promise).rejects.toThrow(error);
+        });
+    });
+});

package/src/internal/photos/apiService.ts

@@ -1,9 +1,13 @@
 import { c } from 'ttag';
 
 import { ValidationError } from '../../errors';
-import { APICodeError, DriveAPIService, drivePaths } from '../apiService';
+import { NodeResultWithError } from '../../interface';
+import { APICodeError, DriveAPIService, drivePaths, InvalidRequirementsAPIError, isCodeOk } from '../apiService';
+import { batch } from '../batch';
 import { EncryptedRootShare, EncryptedShareCrypto, ShareType } from '../shares/interface';
 import { makeNodeUid, splitNodeUid } from '../uids';
+import { MissingRelatedPhotosError } from './errors';
+import { AddToAlbumEncryptedPhotoPayload, AlbumItem } from './interface';
 
 type GetPhotoShareResponse =
     drivePaths['/drive/v2/shares/photos']['get']['responses']['200']['content']['application/json'];
@@ -21,6 +25,9 @@ type GetTimelineResponse =
 type GetAlbumsResponse =
     drivePaths['/drive/photos/volumes/{volumeID}/albums']['get']['responses']['200']['content']['application/json'];
 
+type GetAlbumChildrenResponse =
+    drivePaths['/drive/photos/volumes/{volumeID}/albums/{linkID}/children']['get']['responses']['200']['content']['application/json'];
+
 type PostCreateAlbumRequest = Extract<
     drivePaths['/drive/photos/volumes/{volumeID}/albums']['post']['requestBody'],
     { content: object }
@@ -40,6 +47,27 @@ type PostPhotoDuplicateRequest = Extract<
 type PostPhotoDuplicateResponse =
     drivePaths['/drive/volumes/{volumeID}/photos/duplicates']['post']['responses']['200']['content']['application/json'];
 
+type PostAddPhotosToAlbumRequest = Extract<
+    drivePaths['/drive/photos/volumes/{volumeID}/albums/{linkID}/add-multiple']['post']['requestBody'],
+    { content: object }
+>['content']['application/json'];
+type PostAddPhotosToAlbumResponse =
+    drivePaths['/drive/photos/volumes/{volumeID}/albums/{linkID}/add-multiple']['post']['responses']['200']['content']['application/json'];
+
+type PostCopyLinkRequest = Extract<
+    drivePaths['/drive/volumes/{volumeID}/links/{linkID}/copy']['post']['requestBody'],
+    { content: object }
+>['content']['application/json'];
+type PostCopyLinkResponse =
+    drivePaths['/drive/volumes/{volumeID}/links/{linkID}/copy']['post']['responses']['200']['content']['application/json'];
+
+type PostRemovePhotosFromAlbumRequest = Extract<
+    drivePaths['/drive/photos/volumes/{volumeID}/albums/{linkID}/remove-multiple']['post']['requestBody'],
+    { content: object }
+>['content']['application/json'];
+type PostRemovePhotosFromAlbumResponse =
+    drivePaths['/drive/photos/volumes/{volumeID}/albums/{linkID}/remove-multiple']['post']['responses']['200']['content']['application/json'];
+
 const ALBUM_CONTAINS_PHOTOS_NOT_IN_TIMELINE_ERROR_CODE = 200302;
 
 /**
@@ -173,6 +201,28 @@ export class PhotosAPIService {
         }
     }
 
+    async *iterateAlbumChildren(albumNodeUid: string, signal?: AbortSignal): AsyncGenerator<AlbumItem> {
+        const { volumeId, nodeId: linkId } = splitNodeUid(albumNodeUid);
+        let anchor = '';
+        while (true) {
+            const response = await this.apiService.get<GetAlbumChildrenResponse>(
+                `drive/photos/volumes/${volumeId}/albums/${linkId}/children?Sort=Captured&Desc=1${anchor ? `&AnchorID=${anchor}` : ''}`,
+                signal,
+            );
+            for (const photo of response.Photos) {
+                yield {
+                    nodeUid: makeNodeUid(volumeId, photo.LinkID),
+                    captureTime: new Date(photo.CaptureTime * 1000),
+                };
+            }
+
+            if (!response.More || !response.AnchorID) {
+                break;
+            }
+            anchor = response.AnchorID;
+        }
+    }
+
     async checkPhotoDuplicates(
         volumeId: string,
         nameHashes: string[],
@@ -251,20 +301,17 @@ export class PhotosAPIService {
     ): Promise<void> {
         const { volumeId, nodeId: linkId } = splitNodeUid(albumNodeUid);
         const coverLinkId = coverPhotoNodeUid ? splitNodeUid(coverPhotoNodeUid).nodeId : undefined;
-        await this.apiService.put<PutUpdateAlbumRequest, void>(
-            `drive/photos/volumes/${volumeId}/albums/${linkId}`,
-            {
-                CoverLinkID: coverLinkId,
-                Link: updatedName
-                    ? {
-                          Name: updatedName.encryptedName,
-                          Hash: updatedName.hash,
-                          OriginalHash: updatedName.originalHash,
-                          NameSignatureEmail: updatedName.nameSignatureEmail,
-                      }
-                    : null,
-            },
-        );
+        await this.apiService.put<PutUpdateAlbumRequest, void>(`drive/photos/volumes/${volumeId}/albums/${linkId}`, {
+            CoverLinkID: coverLinkId,
+            Link: updatedName
+                ? {
+                      Name: updatedName.encryptedName,
+                      Hash: updatedName.hash,
+                      OriginalHash: updatedName.originalHash,
+                      NameSignatureEmail: updatedName.nameSignatureEmail,
+                  }
+                : null,
+        });
     }
 
     async deleteAlbum(albumNodeUid: string, options: { force?: boolean } = {}): Promise<void> {
@@ -280,4 +327,176 @@ export class PhotosAPIService {
             throw error;
         }
     }
+
+    /**
+     * Add photos from the same volume to an album.
+     *
+     * To add photos from different volumes, use the {@link copyPhotoToAlbum} method.
+     *
+     * In the future, these two methods will be merged into a single one.
+     */
+    async *addPhotosToAlbum(
+        albumNodeUid: string,
+        photoPayloads: AddToAlbumEncryptedPhotoPayload[],
+        signal?: AbortSignal,
+    ): AsyncGenerator<NodeResultWithError> {
+        const { volumeId, nodeId: albumLinkId } = splitNodeUid(albumNodeUid);
+
+        const allPhotoPayloads = photoPayloads.flatMap((photoPayload) => [
+            photoPayload,
+            ...(photoPayload.relatedPhotos || []),
+        ]);
+        const allPhotoData = allPhotoPayloads.map((photoPayload) => {
+            const { nodeId } = splitNodeUid(photoPayload.nodeUid);
+            return {
+                LinkID: nodeId,
+                Hash: photoPayload.nameHash,
+                Name: photoPayload.encryptedName,
+                NameSignatureEmail: photoPayload.nameSignatureEmail,
+                NodePassphrase: photoPayload.nodePassphrase,
+                ContentHash: photoPayload.contentHash,
+            };
+        });
+
+        const response = await this.apiService.post<PostAddPhotosToAlbumRequest, PostAddPhotosToAlbumResponse>(
+            `drive/photos/volumes/${volumeId}/albums/${albumLinkId}/add-multiple`,
+            {
+                AlbumData: allPhotoData,
+            },
+            signal,
+        );
+
+        const errors = new Map<string, Error>();
+
+        for (const r of response.Responses || []) {
+            // @ts-expect-error - API definition is not correct.
+            const details = r as {
+                LinkID: string;
+                Response: {
+                    Code: number;
+                    Error?: string;
+                    Details: { Missing: string[] };
+                };
+            };
+
+            if (!details.Response.Code || !isCodeOk(details.Response.Code) || details.Response?.Error) {
+                const nodeUid = makeNodeUid(volumeId, details.LinkID);
+
+                if (details.Response.Details?.Missing) {
+                    const missingNodeUids = details.Response.Details.Missing.map((linkId) =>
+                        makeNodeUid(volumeId, linkId),
+                    );
+                    errors.set(nodeUid, new MissingRelatedPhotosError(missingNodeUids));
+                } else {
+                    errors.set(
+                        nodeUid,
+                        new APICodeError(details.Response.Error || c('Error').t`Unknown error`, details.Response.Code),
+                    );
+                }
+            }
+        }
+
+        for (const photoPayload of photoPayloads) {
+            const uid = photoPayload.nodeUid;
+            const error = errors.get(uid);
+            if (error) {
+                yield { uid, ok: false, error };
+            } else {
+                yield { uid, ok: true };
+            }
+        }
+    }
+
+    /**
+     * Copy a photo to a shared album on a different volume.
+     *
+     * 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,
+        payload: AddToAlbumEncryptedPhotoPayload,
+        signal?: AbortSignal,
+    ): Promise<string> {
+        const { volumeId: sourceVolumeId, nodeId: sourceLinkId } = splitNodeUid(payload.nodeUid);
+        const { volumeId: targetVolumeId, nodeId: targetAlbumLinkId } = splitNodeUid(albumNodeUid);
+
+        try {
+            const response = await this.apiService.post<PostCopyLinkRequest, PostCopyLinkResponse>(
+                `drive/volumes/${sourceVolumeId}/links/${sourceLinkId}/copy`,
+                {
+                    TargetVolumeID: targetVolumeId,
+                    TargetParentLinkID: targetAlbumLinkId,
+                    Hash: payload.nameHash,
+                    Name: payload.encryptedName,
+                    NameSignatureEmail: payload.nameSignatureEmail,
+                    NodePassphrase: payload.nodePassphrase,
+                    // @ts-expect-error: API accepts NodePassphraseSignature as optional.
+                    NodePassphraseSignature: payload.nodePassphraseSignature,
+                    // @ts-expect-error: API accepts SignatureEmail as optional.
+                    SignatureEmail: payload.signatureEmail,
+                    Photos: {
+                        ContentHash: payload.contentHash,
+                        RelatedPhotos:
+                            payload.relatedPhotos?.map((related) => ({
+                                LinkID: splitNodeUid(related.nodeUid).nodeId,
+                                Hash: related.nameHash,
+                                Name: related.encryptedName,
+                                NodePassphrase: related.nodePassphrase,
+                                ContentHash: related.contentHash,
+                            })) || [],
+                    },
+                },
+                signal,
+            );
+            return makeNodeUid(targetVolumeId, response.LinkID);
+        } catch (error) {
+            if (error instanceof InvalidRequirementsAPIError) {
+                const { Missing: missingLinkIds } = error.details as { Missing: string[] };
+                if (missingLinkIds.length > 0) {
+                    throw new MissingRelatedPhotosError(
+                        missingLinkIds.map((linkId) => makeNodeUid(sourceVolumeId, linkId)),
+                    );
+                }
+            }
+            throw error;
+        }
+    }
+
+    async *removePhotosFromAlbum(
+        albumNodeUid: string,
+        photoNodeUids: string[],
+        signal?: AbortSignal,
+    ): AsyncGenerator<NodeResultWithError> {
+        const { volumeId, nodeId: albumLinkId } = splitNodeUid(albumNodeUid);
+
+        const batchSize = 50;
+
+        for (const photoNodeUidsBatch of batch(photoNodeUids, batchSize)) {
+            const linkIds = photoNodeUidsBatch.map((nodeUid) => splitNodeUid(nodeUid).nodeId);
+
+            let error: Error | undefined;
+            try {
+                await this.apiService.post<PostRemovePhotosFromAlbumRequest, PostRemovePhotosFromAlbumResponse>(
+                    `drive/photos/volumes/${volumeId}/albums/${albumLinkId}/remove-multiple`,
+                    {
+                        LinkIDs: linkIds,
+                    },
+                    signal,
+                );
+            } catch (e) {
+                error = e instanceof Error ? e : new Error(c('Error').t`Unknown error`);
+            }
+
+            // The API does not return individual results for each photo.
+            for (const uid of photoNodeUidsBatch) {
+                if (error) {
+                    yield { uid, ok: false, error };
+                } else {
+                    yield { uid, ok: true };
+                }
+            }
+        }
+    }
 }

package/src/internal/photos/errors.ts

@@ -0,0 +1,11 @@
+import { c } from 'ttag';
+
+export class MissingRelatedPhotosError extends Error {
+    constructor(public missingNodeUids: string[]) {
+        // We do not want to leak the technical details of the error to the user.
+        // When this error happens, it is retried by the SDK, so very likely the
+        // user will not see this error unless the operation fails twice in a row.
+        super(c('Error').t`Operation failed, try again later`);
+        this.name = 'MissingRelatedPhotosError';
+    }
+}

package/src/internal/photos/index.ts

@@ -33,7 +33,7 @@ import {
     PhotoUploadMetadata,
 } from './upload';
 
-export type { DecryptedPhotoNode } from './interface';
+export type { DecryptedPhotoNode, TimelineItem, AlbumItem, PhotoTag } from './interface';
 
 // Only photos and albums can be shared in photos volume.
 export const PHOTOS_SHARE_TARGET_TYPES = [ShareTargetType.Photo, ShareTargetType.Album];
@@ -60,7 +60,7 @@ export function initPhotosModule(
         photoShares,
         nodesService,
     );
-    const albums = new Albums(api, albumsCryptoService, photoShares, nodesService);
+    const albums = new Albums(telemetry, api, albumsCryptoService, photoShares, nodesService);
 
     return {
         timeline,

package/src/internal/photos/interface.ts

@@ -1,5 +1,5 @@
 import { PrivateKey } from '../../crypto';
-import { MetricVolumeType, PhotoAttributes } from '../../interface';
+import { MetricVolumeType, PhotoAttributes, AlbumAttributes } from '../../interface';
 import { DecryptedNode, EncryptedNode, DecryptedUnparsedNode } from '../nodes/interface';
 import { EncryptedShare } from '../shares';
 
@@ -25,14 +25,17 @@ export interface SharesService {
 
 export type EncryptedPhotoNode = EncryptedNode & {
     photo?: EcnryptedPhotoAttributes;
+    album?: AlbumAttributes;
 };
 
 export type DecryptedUnparsedPhotoNode = DecryptedUnparsedNode & {
     photo?: PhotoAttributes;
+    album?: AlbumAttributes;
 };
 
 export type DecryptedPhotoNode = DecryptedNode & {
     photo?: PhotoAttributes;
+    album?: AlbumAttributes;
 };
 
 export type EcnryptedPhotoAttributes = Omit<PhotoAttributes, 'albums'> & {
@@ -42,3 +45,39 @@ export type EcnryptedPhotoAttributes = Omit<PhotoAttributes, 'albums'> & {
         contentHash?: string;
     })[];
 };
+
+export type TimelineItem = {
+    nodeUid: string;
+    captureTime: Date;
+    tags: PhotoTag[];
+};
+
+export type AlbumItem = {
+    nodeUid: string;
+    captureTime: Date;
+};
+
+export enum PhotoTag {
+    Favorites = 0,
+    Screenshots = 1,
+    Videos = 2,
+    LivePhotos = 3,
+    MotionPhotos = 4,
+    Selfies = 5,
+    Portraits = 6,
+    Bursts = 7,
+    Panoramas = 8,
+    Raw = 9,
+}
+
+export type AddToAlbumEncryptedPhotoPayload = {
+    nodeUid: string;
+    contentHash: string;
+    nameHash: string;
+    encryptedName: string;
+    nameSignatureEmail: string;
+    nodePassphrase: string;
+    nodePassphraseSignature?: string;
+    signatureEmail?: string;
+    relatedPhotos?: Omit<AddToAlbumEncryptedPhotoPayload, 'relatedPhotos'>[];
+};