@protontech/drive-sdk 0.9.8 → 0.10.0

package/src/internal/upload/chunkStreamReader.test.ts

@@ -1,10 +1,10 @@
 import { ChunkStreamReader } from './chunkStreamReader';
 
 describe('ChunkStreamReader', () => {
-    let stream: ReadableStream<Uint8Array>;
+    let stream: ReadableStream<Uint8Array<ArrayBuffer>>;
 
     beforeEach(() => {
-        stream = new ReadableStream<Uint8Array>({
+        stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
             start(controller) {
                 controller.enqueue(new Uint8Array([1, 2, 3]));
                 controller.enqueue(new Uint8Array([4, 5, 6]));
@@ -18,7 +18,7 @@ describe('ChunkStreamReader', () => {
     it('should yield chunks as enqueued if matching the size', async () => {
         const reader = new ChunkStreamReader(stream, 3);
 
-        const chunks: Uint8Array[] = [];
+        const chunks: Uint8Array<ArrayBuffer>[] = [];
         for await (const chunk of reader.iterateChunks()) {
             chunks.push(new Uint8Array(chunk));
         }
@@ -33,7 +33,7 @@ describe('ChunkStreamReader', () => {
     it('should yield smaller chunks than enqueued chunks', async () => {
         const reader = new ChunkStreamReader(stream, 2);
 
-        const chunks: Uint8Array[] = [];
+        const chunks: Uint8Array<ArrayBuffer>[] = [];
         for await (const chunk of reader.iterateChunks()) {
             chunks.push(new Uint8Array(chunk));
         }
@@ -50,7 +50,7 @@ describe('ChunkStreamReader', () => {
     it('should yield bigger chunks than enqueued chunks', async () => {
         const reader = new ChunkStreamReader(stream, 4);
 
-        const chunks: Uint8Array[] = [];
+        const chunks: Uint8Array<ArrayBuffer>[] = [];
         for await (const chunk of reader.iterateChunks()) {
             chunks.push(new Uint8Array(chunk));
         }
@@ -64,7 +64,7 @@ describe('ChunkStreamReader', () => {
     it('should yield last incomplete chunk', async () => {
         const reader = new ChunkStreamReader(stream, 5);
 
-        const chunks: Uint8Array[] = [];
+        const chunks: Uint8Array<ArrayBuffer>[] = [];
         for await (const chunk of reader.iterateChunks()) {
             chunks.push(new Uint8Array(chunk));
         }
@@ -78,7 +78,7 @@ describe('ChunkStreamReader', () => {
     it('should yield as one big chunk', async () => {
         const reader = new ChunkStreamReader(stream, 100);
 
-        const chunks: Uint8Array[] = [];
+        const chunks: Uint8Array<ArrayBuffer>[] = [];
         for await (const chunk of reader.iterateChunks()) {
             chunks.push(new Uint8Array(chunk));
         }

package/src/internal/upload/chunkStreamReader.ts

@@ -6,16 +6,16 @@
  * If you need to keep previous chunks, copy them to a new array.
  */
 export class ChunkStreamReader {
-    private reader: ReadableStreamDefaultReader<Uint8Array>;
+    private reader: ReadableStreamDefaultReader<Uint8Array<ArrayBuffer>>;
 
     private chunkSize: number;
 
-    constructor(stream: ReadableStream<Uint8Array>, chunkSize: number) {
+    constructor(stream: ReadableStream<Uint8Array<ArrayBuffer>>, chunkSize: number) {
         this.reader = stream.getReader();
         this.chunkSize = chunkSize;
     }
 
-    async *iterateChunks(): AsyncGenerator<Uint8Array> {
+    async *iterateChunks(): AsyncGenerator<Uint8Array<ArrayBuffer>> {
         const buffer = new Uint8Array(this.chunkSize);
 
         let position = 0;

package/src/internal/upload/cryptoService.ts

@@ -23,7 +23,7 @@ export class UploadCryptoService {
 
     async generateFileCrypto(
         parentUid: string,
-        parentKeys: { key: PrivateKey; hashKey: Uint8Array },
+        parentKeys: { key: PrivateKey; hashKey: Uint8Array<ArrayBuffer> },
         name: string,
     ): Promise<NodeCrypto> {
         const signingKeys = await this.getSigningKeys({ parentNodeUid: parentUid });
@@ -118,14 +118,14 @@ export class UploadCryptoService {
             encryptedData: encryptedData,
             originalSize: thumbnail.thumbnail.length,
             encryptedSize: encryptedData.length,
-            hash: new Uint8Array(digest),
+            hash: new Uint8Array<ArrayBuffer>(digest),
         };
     }
 
     async encryptBlock(
-        verifyBlock: (encryptedBlock: Uint8Array) => Promise<{ verificationToken: Uint8Array }>,
+        verifyBlock: (encryptedBlock: Uint8Array<ArrayBuffer>) => Promise<{ verificationToken: Uint8Array<ArrayBuffer> }>,
         nodeRevisionDraftKeys: NodeRevisionDraftKeys,
-        block: Uint8Array,
+        block: Uint8Array<ArrayBuffer>,
         index: number,
     ): Promise<EncryptedBlock> {
         const { encryptedData, armoredSignature } = await this.driveCrypto.encryptBlock(
@@ -145,13 +145,13 @@ export class UploadCryptoService {
             verificationToken,
             originalSize: block.length,
             encryptedSize: encryptedData.length,
-            hash: new Uint8Array(digest),
+            hash: new Uint8Array<ArrayBuffer>(digest),
         };
     }
 
     async commitFile(
         nodeRevisionDraftKeys: NodeRevisionDraftKeys,
-        manifest: Uint8Array,
+        manifest: Uint8Array<ArrayBuffer>,
         extendedAttributes?: string,
     ): Promise<{
         armoredManifestSignature: string;
@@ -190,10 +190,10 @@ export class UploadCryptoService {
 
     async verifyBlock(
         contentKeyPacketSessionKey: SessionKey,
-        verificationCode: Uint8Array,
-        encryptedData: Uint8Array,
+        verificationCode: Uint8Array<ArrayBuffer>,
+        encryptedData: Uint8Array<ArrayBuffer>,
     ): Promise<{
-        verificationToken: Uint8Array;
+        verificationToken: Uint8Array<ArrayBuffer>;
     }> {
         // Attempt to decrypt data block, to try to detect bitflips / bad hardware
         //

package/src/internal/upload/interface.ts

@@ -8,7 +8,7 @@ export type NodeRevisionDraft = {
     nodeRevisionUid: string;
     nodeKeys: NodeRevisionDraftKeys;
     parentNodeKeys?: {
-        hashKey: Uint8Array;
+        hashKey: Uint8Array<ArrayBuffer>;
     };
     // newNodeInfo is set only when revision is created with the new node.
     newNodeInfo?: {
@@ -64,19 +64,19 @@ export type NodeCryptoSigningKeys = {
 export type EncryptedBlockMetadata = {
     encryptedSize: number;
     originalSize: number;
-    hash: Uint8Array;
+    hash: Uint8Array<ArrayBuffer>;
 };
 
 export type EncryptedBlock = EncryptedBlockMetadata & {
     index: number;
-    encryptedData: Uint8Array;
+    encryptedData: Uint8Array<ArrayBuffer>;
     armoredSignature: string;
-    verificationToken: Uint8Array;
+    verificationToken: Uint8Array<ArrayBuffer>;
 };
 
 export type EncryptedThumbnail = EncryptedBlockMetadata & {
     type: ThumbnailType;
-    encryptedData: Uint8Array;
+    encryptedData: Uint8Array<ArrayBuffer>;
 };
 
 export type UploadTokens = {
@@ -101,7 +101,7 @@ export interface NodesService {
         key: PrivateKey;
         passphraseSessionKey: SessionKey;
         contentKeyPacketSessionKey?: SessionKey;
-        hashKey?: Uint8Array;
+        hashKey?: Uint8Array<ArrayBuffer>;
     }>;
     getNodeSigningKeys(
         uids: { nodeUid: string; parentNodeUid?: string } | { nodeUid?: string; parentNodeUid: string },

package/src/internal/upload/manager.ts

@@ -73,7 +73,7 @@ export class UploadManager {
 
     private async createDraftOnAPI(
         parentFolderUid: string,
-        parentHashKey: Uint8Array,
+        parentHashKey: Uint8Array<ArrayBuffer>,
         name: string,
         metadata: UploadMetadata,
         generatedNodeCrypto: NodeCrypto,
@@ -226,7 +226,7 @@ export class UploadManager {
 
     async commitDraft(
         nodeRevisionDraft: NodeRevisionDraft,
-        manifest: Uint8Array,
+        manifest: Uint8Array<ArrayBuffer>,
         extendedAttributes: {
             modificationTime?: Date;
             size: number;

package/src/internal/upload/streamUploader.ts

@@ -655,7 +655,7 @@ export class StreamUploader {
         return uploadedBlocks.map((block) => block.originalSize);
     }
 
-    protected get manifest(): Uint8Array {
+    protected get manifest(): Uint8Array<ArrayBuffer> {
         this.uploadedThumbnails.sort((a, b) => a.type - b.type);
         this.uploadedBlocks.sort((a, b) => a.index - b.index);
         const hashes = [

package/src/protonDriveClient.ts

@@ -223,12 +223,12 @@ export class ProtonDriveClient {
                 return keys.contentKeyPacketSessionKey;
             },
             getPublicLinkInfo: async (url: string) => {
-                const { token } = getTokenAndPasswordFromUrl(url)
+                const { token } = getTokenAndPasswordFromUrl(url);
                 this.logger.info(`Getting info for public link token ${token}`);
                 return this.publicSessionManager.getInfo(token);
             },
             authPublicLink: async (url: string, customPassword?: string, isAnonymousContext: boolean = false) => {
-                const { token, password: urlPassword } = getTokenAndPasswordFromUrl(url)
+                const { token, password: urlPassword } = getTokenAndPasswordFromUrl(url);
                 this.logger.info(`Authenticating public link token ${token}`);
 
                 const { httpClient, shareKey, rootUid, publicRole } = await this.publicSessionManager.auth(
@@ -681,7 +681,7 @@ export class ProtonDriveClient {
      * @param customPassword - The optional custom password.
      */
     async createBookmark(url: string, customPassword?: string): Promise<void> {
-        const { token, password: urlPassword } = getTokenAndPasswordFromUrl(url)
+        const { token, password: urlPassword } = getTokenAndPasswordFromUrl(url);
         this.logger.info(`Creating bookmark for token ${token}`);
         await this.sharing.access.createBookmark(token, urlPassword, customPassword);
     }
@@ -912,6 +912,18 @@ export class ProtonDriveClient {
         yield* this.devices.iterateDevices(signal);
     }
 
+    /**
+     * Get the device entity by its UID.
+     *
+     * @param deviceOrUid - Device entity or its UID string.
+     * @returns The device entity.
+     * @throws {@link ValidationError} If the device is not found.
+     */
+    async getDevice(deviceOrUid: DeviceOrUid): Promise<Device> {
+        this.logger.info(`Getting device ${getUid(deviceOrUid)}`);
+        return this.devices.getDevice(getUid(deviceOrUid));
+    }
+
     /**
      * Creates a new device.
      *

package/src/protonDrivePhotosClient.ts

@@ -17,6 +17,7 @@ import {
     NonProtonInvitationOrUid,
     ProtonInvitationWithNode,
     NodeResult,
+    NodeResultWithError,
 } from './interface';
 import { getConfig } from './config';
 import { DriveCrypto } from './crypto';
@@ -38,6 +39,9 @@ import {
     initPhotoSharesModule,
     initPhotoUploadModule,
     initPhotosNodesModule,
+    AlbumItem,
+    TimelineItem,
+    PhotoTag,
 } from './internal/photos';
 import { SDKEvents } from './internal/sdkEvents';
 import { initSharesModule } from './internal/shares';
@@ -117,13 +121,7 @@ export class ProtonDrivePhotosClient {
             this.photoShares,
             fullConfig.clientUid,
         );
-        this.photos = initPhotosModule(
-            telemetry,
-            apiService,
-            cryptoModule,
-            this.photoShares,
-            this.nodes.access,
-        );
+        this.photos = initPhotosModule(telemetry, apiService, cryptoModule, this.photoShares, this.nodes.access);
         this.sharing = initSharingModule(
             telemetry,
             apiService,
@@ -224,12 +222,7 @@ export class ProtonDrivePhotosClient {
      * The output is sorted by the capture time, starting from the
      * the most recent photos.
      */
-    async *iterateTimeline(signal?: AbortSignal): AsyncGenerator<{
-        nodeUid: string;
-        captureTime: Date;
-        tags: number[];
-    }> {
-        // TODO: expose better type
+    async *iterateTimeline(signal?: AbortSignal): AsyncGenerator<TimelineItem> {
         yield* this.photos.timeline.iterateTimeline(signal);
     }
 
@@ -240,7 +233,7 @@ export class ProtonDrivePhotosClient {
      */
     async *iterateTrashedNodes(signal?: AbortSignal): AsyncGenerator<MaybePhotoNode> {
         this.logger.info('Iterating trashed nodes');
-        yield * convertInternalPhotoNodeIterator(this.nodes.access.iterateTrashedNodes(signal));
+        yield* convertInternalPhotoNodeIterator(this.nodes.access.iterateTrashedNodes(signal));
     }
 
     /**
@@ -251,7 +244,7 @@ export class ProtonDrivePhotosClient {
     async *iterateNodes(nodeUids: NodeOrUid[], signal?: AbortSignal): AsyncGenerator<MaybeMissingPhotoNode> {
         this.logger.info(`Iterating ${nodeUids.length} nodes`);
         // TODO: expose photo type
-        yield * convertInternalMissingPhotoNodeIterator(this.nodes.access.iterateNodes(getUids(nodeUids), signal));
+        yield* convertInternalMissingPhotoNodeIterator(this.nodes.access.iterateNodes(getUids(nodeUids), signal));
     }
 
     /**
@@ -301,7 +294,7 @@ export class ProtonDrivePhotosClient {
      */
     async *deleteNodes(nodeUids: NodeOrUid[], signal?: AbortSignal): AsyncGenerator<NodeResult> {
         this.logger.info(`Deleting ${nodeUids.length} nodes`);
-        yield * this.nodes.management.deleteTrashedNodes(getUids(nodeUids), signal);
+        yield* this.nodes.management.deleteTrashedNodes(getUids(nodeUids), signal);
     }
 
     /**
@@ -319,7 +312,7 @@ export class ProtonDrivePhotosClient {
      */
     async *iterateSharedNodes(signal?: AbortSignal): AsyncGenerator<MaybePhotoNode> {
         this.logger.info('Iterating shared nodes by me');
-        yield * convertInternalPhotoNodeIterator(this.sharing.access.iterateSharedNodes(signal));
+        yield* convertInternalPhotoNodeIterator(this.sharing.access.iterateSharedNodes(signal));
     }
 
     /**
@@ -456,8 +449,7 @@ export class ProtonDrivePhotosClient {
         metadata: UploadMetadata & {
             captureTime?: Date;
             mainPhotoLinkID?: string;
-            // TODO: handle tags enum in the SDK
-            tags?: (0 | 3 | 1 | 2 | 7 | 4 | 5 | 6 | 8 | 9)[];
+            tags?: PhotoTag[];
         },
         signal?: AbortSignal,
     ): Promise<FileUploader> {
@@ -487,7 +479,9 @@ export class ProtonDrivePhotosClient {
      */
     async isDuplicatePhoto(name: string, generateSha1: () => Promise<string>, signal?: AbortSignal): Promise<boolean> {
         this.logger.info(`Checking if photo is a duplicate`);
-        return this.photos.timeline.findPhotoDuplicates(name, generateSha1, signal).then(nodeUids => nodeUids.length !== 0);
+        return this.photos.timeline
+            .findPhotoDuplicates(name, generateSha1, signal)
+            .then((nodeUids) => nodeUids.length !== 0);
     }
 
     /**
@@ -508,7 +502,11 @@ export class ProtonDrivePhotosClient {
      * @param signal - An optional abort signal to cancel the operation.
      * @returns An array of node UIDs of duplicate photos. Empty array if no duplicates found.
      */
-    async findPhotoDuplicates(name: string, generateSha1: () => Promise<string>, signal?: AbortSignal): Promise<string[]> {
+    async findPhotoDuplicates(
+        name: string,
+        generateSha1: () => Promise<string>,
+        signal?: AbortSignal,
+    ): Promise<string[]> {
         this.logger.info(`Checking if photo have duplicates`);
         return this.photos.timeline.findPhotoDuplicates(name, generateSha1, signal);
     }
@@ -578,6 +576,64 @@ export class ProtonDrivePhotosClient {
     async *iterateAlbums(signal?: AbortSignal): AsyncGenerator<MaybePhotoNode> {
         this.logger.info('Iterating albums');
         // TODO: expose album type
-        yield * convertInternalPhotoNodeIterator(this.photos.albums.iterateAlbums(signal));
+        yield* convertInternalPhotoNodeIterator(this.photos.albums.iterateAlbums(signal));
+    }
+
+    /**
+     * Iterates the photo placeholders of the given album.
+     *
+     * The output is sorted by the capture time, starting from the
+     * the most recent photos.
+     *
+     * @param albumNodeUid - The UID of the album.
+     * @param signal - An optional abort the operation.
+     */
+    async *iterateAlbum(albumNodeUid: NodeOrUid, signal?: AbortSignal): AsyncGenerator<AlbumItem> {
+        this.logger.info(`Iterating photos of album ${getUid(albumNodeUid)}`);
+        yield* this.photos.albums.iterateAlbum(getUid(albumNodeUid), signal);
+    }
+
+    /**
+     * Adds photos to an album.
+     *
+     * Photos are added in batches. Each photo's related photos (e.g., live
+     * photo components) are always included with the main photo.
+     *
+     * The album has a limit of 10,000 photos. If the limit is reached,
+     * a `ValidationError` is thrown.
+     *
+     * @param albumNodeUid - The UID of the album to add photos to.
+     * @param photoNodeUids - The UIDs of the photos to add to the album.
+     * @param signal - An optional abort signal to cancel the operation.
+     * @returns An async generator of the added photo results.
+     */
+    async *addPhotosToAlbum(
+        albumNodeUid: NodeOrUid,
+        photoNodeUids: NodeOrUid[],
+        signal?: AbortSignal,
+    ): AsyncGenerator<NodeResultWithError> {
+        this.logger.info(`Adding ${photoNodeUids.length} photos to album ${getUid(albumNodeUid)}`);
+        yield* this.photos.albums.addPhotos(getUid(albumNodeUid), getUids(photoNodeUids), signal);
+    }
+
+    /**
+     * Removes photos from an album.
+     *
+     * Photos are not deleted, they are just removed from the album.
+     * If a photo was added to the timeline by the user, it will remain
+     * in the timeline after being removed from the album.
+     *
+     * @param albumNodeUid - The UID of the album to remove photos from.
+     * @param photoNodeUids - The UIDs of the photos to remove from the album.
+     * @param signal - An optional abort signal to cancel the operation.
+     * @returns An async generator of the removed photo results.
+     */
+    async *removePhotosFromAlbum(
+        albumNodeUid: NodeOrUid,
+        photoNodeUids: NodeOrUid[],
+        signal?: AbortSignal,
+    ): AsyncGenerator<NodeResultWithError> {
+        this.logger.info(`Removing ${photoNodeUids.length} photos from album ${getUid(albumNodeUid)}`);
+        yield* this.photos.albums.removePhotos(getUid(albumNodeUid), getUids(photoNodeUids), signal);
     }
 }

package/src/protonDrivePublicLinkClient.ts

@@ -350,4 +350,17 @@ export class ProtonDrivePublicLinkClient {
         this.logger.info(`Getting file revision uploader for ${getUid(nodeUid)}`);
         return this.upload.getFileRevisionUploader(getUid(nodeUid), metadata, signal);
     }
+
+    /**
+     * Returns the available name for the file in the given parent folder.
+     *
+     * The function will return a name that includes the original name with the
+     * available index. The name is guaranteed to be unique in the parent folder.
+     *
+     * Example new name: `file (2).txt`.
+     */
+    async getAvailableName(parentFolderUid: NodeOrUid, name: string): Promise<string> {
+        this.logger.info(`Getting available name in folder ${getUid(parentFolderUid)}`);
+        return this.sharingPublic.nodes.management.findAvailableName(getUid(parentFolderUid), name);
+    }
 }

package/src/transformers.ts

@@ -160,11 +160,13 @@ export function convertInternalPhotoNode(photoNode: InternalPartialPhotoNode): P
         return resultOk({
             ...node.value,
             photo: photoNode.photo,
+            album: photoNode.album,
         } as PublicPhotoNode);
     }
     return resultError({
         ...node.error,
         photo: photoNode.photo,
+        album: photoNode.album,
     } as PublicDegradedPhotoNode);
 }