@protontech/drive-sdk 0.0.13 → 0.1.0

package/src/diagnostic/zipGenerators.test.ts

@@ -0,0 +1,177 @@
+import { zipGenerators } from './zipGenerators';
+
+async function* createTimedGenerator<T>(values: { value: T; delay: number }[]): AsyncGenerator<T> {
+    for (const { value, delay } of values) {
+        await new Promise(resolve => setTimeout(resolve, delay));
+        yield value;
+    }
+}
+
+async function* createEmptyGenerator<T>(): AsyncGenerator<T> {
+    return;
+}
+
+describe('zipGenerators', () => {
+    it('should handle both generators being empty', async () => {
+        const genA = createEmptyGenerator<string>();
+        const genB = createEmptyGenerator<number>();
+
+        const result: (string | number)[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        for await (const value of zipGen) {
+            result.push(value);
+        }
+
+        expect(result).toEqual([]);
+    });
+
+    it('should handle one generator being empty (first empty)', async () => {
+        const genA = createEmptyGenerator<string>();
+        const genB = createTimedGenerator([
+            { value: 1, delay: 10 },
+            { value: 2, delay: 10 },
+        ]);
+
+        const result: (string | number)[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        const promise = (async () => {
+            for await (const value of zipGen) {
+                result.push(value);
+            }
+        })();
+
+        await promise;
+
+        expect(result).toEqual([1, 2]);
+    });
+
+    it('should handle one generator being empty (second empty)', async () => {
+        const genA = createTimedGenerator([
+            { value: 'a', delay: 10 },
+            { value: 'b', delay: 10 },
+        ]);
+        const genB = createEmptyGenerator<number>();
+
+        const result: (string | number)[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        const promise = (async () => {
+            for await (const value of zipGen) {
+                result.push(value);
+            }
+        })();
+
+        await promise;
+
+        expect(result).toEqual(['a', 'b']);
+    });
+
+    it('should handle both generators with same number of elements yielded at same time', async () => {
+        const genA = createTimedGenerator([
+            { value: 'a1', delay: 10 },
+            { value: 'a2', delay: 10 },
+            { value: 'a3', delay: 10 },
+        ]);
+        const genB = createTimedGenerator([
+            { value: 'b1', delay: 10 },
+            { value: 'b2', delay: 10 },
+            { value: 'b3', delay: 10 },
+        ]);
+
+        const result: string[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        const promise = (async () => {
+            for await (const value of zipGen) {
+                result.push(value);
+            }
+        })();
+
+        await promise;
+
+        // Since they yield at the same time, the order depends on Promise.race behavior
+        // Both values should be present, but order may vary
+        expect(result).toHaveLength(6);
+        expect(result).toEqual(expect.arrayContaining(['a1', 'a2', 'a3', 'b1', 'b2', 'b3']));
+    });
+
+    it('should handle generators with different timing - first generator faster', async () => {
+        const genA = createTimedGenerator([
+            { value: 'fast1', delay: 10 },
+            { value: 'fast2', delay: 10 },
+            { value: 'fast3', delay: 10 },
+        ]);
+        const genB = createTimedGenerator([
+            { value: 'slow1', delay: 50 },
+            { value: 'slow2', delay: 50 },
+        ]);
+
+        const result: string[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        const promise = (async () => {
+            for await (const value of zipGen) {
+                result.push(value);
+            }
+        })();
+
+        await promise;
+
+        expect(result).toEqual(['fast1', 'fast2', 'fast3', 'slow1', 'slow2']);
+    });
+
+    it('should handle generators with different timing - second generator faster', async () => {
+        const genA = createTimedGenerator([
+            { value: 'slow1', delay: 50 },
+            { value: 'slow2', delay: 50 },
+        ]);
+        const genB = createTimedGenerator([
+            { value: 'fast1', delay: 10 },
+            { value: 'fast2', delay: 10 },
+            { value: 'fast3', delay: 10 },
+        ]);
+
+        const result: string[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        const promise = (async () => {
+            for await (const value of zipGen) {
+                result.push(value);
+            }
+        })();
+
+        await promise;
+
+        expect(result).toEqual(['fast1', 'fast2', 'fast3', 'slow1', 'slow2']);
+    });
+
+    it('should handle mixed timing with overlapping yields', async () => {
+        const genA = createTimedGenerator([
+            { value: 'A1', delay: 50 },
+            { value: 'A2', delay: 100 },
+            { value: 'A3', delay: 100 },
+        ]);
+        const genB = createTimedGenerator([
+            { value: 'B1', delay: 100 },
+            { value: 'B2', delay: 100 },
+            { value: 'B3', delay: 200 },
+        ]);
+
+        const result: string[] = [];
+        const timestamps: number[] = [];
+        const zipGen = zipGenerators(genA, genB);
+
+        const promise = (async () => {
+            for await (const value of zipGen) {
+                result.push(value);
+                timestamps.push(Date.now());
+            }
+        })();
+
+        await promise;
+
+        expect(result).toEqual(['A1', 'B1', 'A2', 'B2', 'A3', 'B3']);
+    });
+});

package/src/diagnostic/zipGenerators.ts

@@ -0,0 +1,70 @@
+/**
+ * Zips two generators into one.
+ *
+ * The combined generator yields values from both generators in the order they
+ * are produced.
+ */
+export async function* zipGenerators<T, U>(
+    genA: AsyncGenerator<T>,
+    genB: AsyncGenerator<U>,
+    options?: {
+        stopOnFirstDone?: boolean
+    },
+): AsyncGenerator<T | U> {
+    const { stopOnFirstDone = false } = options || {};
+
+    const itA = genA[Symbol.asyncIterator]();
+    const itB = genB[Symbol.asyncIterator]();
+
+    let promiseA: Promise<IteratorResult<T>> | undefined = itA.next();
+    let promiseB: Promise<IteratorResult<U>> | undefined = itB.next();
+
+    while (promiseA && promiseB) {
+        const result = await Promise.race([
+            promiseA.then(res => ({ source: 'A' as const, result: res })),
+            promiseB.then(res => ({ source: 'B' as const, result: res }))
+        ]);
+
+        if (result.source === 'A') {
+            if (result.result.done) {
+                promiseA = undefined;
+                if (stopOnFirstDone) {
+                    break;
+                }
+            } else {
+                yield result.result.value;
+                promiseA = itA.next();
+            }
+        } else {
+            if (result.result.done) {
+                promiseB = undefined;
+                if (stopOnFirstDone) {
+                    break;
+                }
+            } else {
+                yield result.result.value;
+                promiseB = itB.next();
+            }
+        }
+    }
+
+    if (stopOnFirstDone) {
+        return;
+    }
+
+    if (promiseA) {
+        const result = await promiseA;
+        if (!result.done) {
+            yield result.value;
+        }
+        yield* itA;
+    }
+
+    if (promiseB) {
+        const result = await promiseB;
+        if (!result.done) {
+            yield result.value;
+        }
+        yield* itB;
+    }
+}

package/src/errors.ts

@@ -75,9 +75,12 @@ export class NodeAlreadyExistsValidationError extends ValidationError {
 
     public readonly existingNodeUid?: string;
 
-    constructor(message: string, code: number, existingNodeUid?: string) {
+    public readonly ongoingUploadByOtherClient: boolean;
+
+    constructor(message: string, code: number, existingNodeUid?: string, ongoingUploadByOtherClient = false) {
         super(message, code);
         this.existingNodeUid = existingNodeUid;
+        this.ongoingUploadByOtherClient = ongoingUploadByOtherClient;
     }
 }
 

package/src/interface/config.ts

@@ -0,0 +1,28 @@
+export type ProtonDriveConfig = {
+    /**
+     * The base URL for the Proton Drive (without schema).
+     *
+     * If not provided, defaults to 'drive-api.proton.me'.
+     */
+    baseUrl?: string,
+
+    /**
+     * The language to use for error messages.
+     *
+     * If not provided, defaults to 'en'.
+     */
+    language?: string,
+
+    /**
+     * Client UID is used to identify the client for the upload.
+     *
+     * If the upload failed because of the existing draft, the SDK will
+     * automatically clean up the existing draft and start a new upload.
+     * If the client UID doesn't match, the SDK throws and then you need
+     * to explicitely ask the user to override the existing draft.
+     *
+     * You can force the upload by setting up
+     * `overrideExistingDraftByOtherClient` to true.
+     */
+    clientUid?: string,
+}

package/src/interface/download.ts

@@ -15,14 +15,14 @@ export interface FileDownloader {
      * 
      * @param onProgress - Callback that is called with the number of downloaded bytes
      */
-    writeToStream(streamFactory: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController,
+    writeToStream(streamFactory: WritableStream, onProgress?: (downloadedBytes: number) => void): DownloadController,
 
     /**
      * Same as `writeToStream` but without verification checks.
      * 
      * Use this only for debugging purposes.
      */
-    unsafeWriteToStream(streamFactory: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController,
+    unsafeWriteToStream(streamFactory: WritableStream, onProgress?: (downloadedBytes: number) => void): DownloadController,
 }
 
 export interface DownloadController {

package/src/interface/events.ts

@@ -1,30 +1,75 @@
-import { Device } from './devices';
-import { MaybeNode } from './nodes';
+export enum SDKEvent {
+    TransfersPaused = "transfersPaused",
+    TransfersResumed = "transfersResumed",
+    RequestsThrottled = "requestsThrottled",
+    RequestsUnthrottled = "requestsUnthrottled",
+}
 
-export type DeviceEventCallback = (deviceEvent: DeviceEvent) => void;
-export type NodeEventCallback = (nodeEvent: NodeEvent) => void;
+export interface LatestEventIdProvider {
+    getLatestEventId(treeEventScopeId: string): string | null;
+}
+
+/**
+ * Callback that accepts list of Drive events and flag whether no
+ * event should be processed, but rather full cache refresh should be
+ * performed.
+ *
+ * Drive listeners should never throw and be wrapped in a try-catch loop.
+ *
+ * @param fullRefreshVolumeId - ID of the volume that should be fully refreshed.
+ */
+export type DriveListener = (event: DriveEvent) => Promise<void>;
+
+type NodeCruEventType = DriveEventType.NodeCreated | DriveEventType.NodeUpdated;
 
 export type NodeEvent = {
-    type: 'update',
-    uid: string,
-    node: MaybeNode,
+    type: NodeCruEventType,
+    nodeUid: string,
+    parentNodeUid?: string,
+    isTrashed: boolean,
+    isShared: boolean,
+    treeEventScopeId: string,
+    eventId: string,
 } | {
-    type: 'remove',
-    uid: string,
+    type: DriveEventType.NodeDeleted,
+    nodeUid: string,
+    parentNodeUid?: string,
+    treeEventScopeId: string,
+    eventId: string,
 }
 
-export type DeviceEvent = {
-    type: 'update',
-    uid: string,
-    device: Device,
-} | {
-    type: 'remove',
-    uid: string,
+export type FastForwardEvent = {
+    type: DriveEventType.FastForward,
+    treeEventScopeId: string,
+    eventId: string,
 }
 
-export enum SDKEvent {
-    TransfersPaused = "transfersPaused",
-    TransfersResumed = "transfersResumed",
-    RequestsThrottled = "requestsThrottled",
-    RequestsUnthrottled = "requestsUnthrottled",
+export type TreeRefreshEvent = {
+    type: DriveEventType.TreeRefresh,
+    treeEventScopeId: string,
+    eventId: string,
+}
+
+export type TreeRemovalEvent = {
+    type: DriveEventType.TreeRemove,
+    treeEventScopeId: string,
+    eventId: 'none',
+}
+
+export type SharedWithMeUpdated = {
+    type: DriveEventType.SharedWithMeUpdated,
+    eventId: string,
+    treeEventScopeId: 'core',
+}
+
+export type DriveEvent = NodeEvent | FastForwardEvent | TreeRefreshEvent | TreeRemovalEvent | FastForwardEvent | SharedWithMeUpdated;
+
+export enum DriveEventType {
+    NodeCreated = 'node_created',
+    NodeUpdated = 'node_updated',
+    NodeDeleted = 'node_deleted',
+    SharedWithMeUpdated = 'shared_with_me_updated',
+    TreeRefresh = 'tree_refresh',
+    TreeRemove = 'tree_remove',
+    FastForward = 'fast_forward'
 }

package/src/interface/httpClient.ts

@@ -24,19 +24,3 @@ type ProtonDriveHTTPClientBaseOptions = {
     timeoutMs: number,
     signal?: AbortSignal,
 }
-
-export type ProtonDriveConfig = {
-    /**
-     * The base URL for the Proton Drive (without schema).
-     *
-     * If not provided, defaults to 'drive-api.proton.me'.
-     */
-    baseUrl?: string,
-
-    /**
-     * The language to use for error messages.
-     *
-     * If not provided, defaults to 'en'.
-     */
-    language?: string,
-}

package/src/interface/index.ts

@@ -1,19 +1,22 @@
 import { ProtonDriveCache } from '../cache';
 import { OpenPGPCrypto, PrivateKey, SessionKey, SRPModule } from '../crypto';
+import { LatestEventIdProvider } from '../internal/events/interface';
 import { ProtonDriveAccount } from './account';
-import { ProtonDriveHTTPClient, ProtonDriveConfig } from './httpClient';
+import { ProtonDriveConfig } from './config';
+import { ProtonDriveHTTPClient } from './httpClient';
 import { Telemetry, MetricEvent } from './telemetry';
 
 export type { Result } from './result';
 export { resultOk, resultError } from './result';
 export type { ProtonDriveAccount, ProtonDriveAccountAddress } from './account';
 export type { Author, UnverifiedAuthorError, AnonymousUser } from './author';
+export type { ProtonDriveConfig } from './config';
 export type { Device, DeviceOrUid } from './devices';
 export { DeviceType } from './devices';
 export type { FileDownloader, DownloadController } from './download';
-export type { NodeEvent, DeviceEvent, DeviceEventCallback, NodeEventCallback } from './events';
-export { SDKEvent } from './events';
-export type { ProtonDriveHTTPClient, ProtonDriveHTTPClientJsonOptions, ProtonDriveHTTPClientBlobOptions, ProtonDriveConfig } from './httpClient';
+export type { DriveListener, LatestEventIdProvider, DriveEvent } from './events';
+export { DriveEventType, SDKEvent } from './events';
+export type { ProtonDriveHTTPClient, ProtonDriveHTTPClientJsonOptions, ProtonDriveHTTPClientBlobOptions } from './httpClient';
 export type { MaybeNode, NodeEntity, DegradedNode, MaybeMissingNode, MissingNode, InvalidNameError, Revision, NodeOrUid, RevisionOrUid, NodeResult } from './nodes';
 export { NodeType, MemberRole, RevisionState } from './nodes';
 export type { ProtonInvitation, ProtonInvitationWithNode, NonProtonInvitation, Member, PublicLink, MaybeBookmark, Bookmark, DegradedBookmark, ProtonInvitationOrUid, NonProtonInvitationOrUid, BookmarkOrUid, ShareNodeSettings, UnshareNodeSettings, ShareMembersSettings, SharePublicLinkSettings, SharePublicLinkSettingsObject, ShareResult } from './sharing';
@@ -43,4 +46,5 @@ export interface ProtonDriveClientContructorParameters {
     srpModule: SRPModule,
     config?: ProtonDriveConfig,
     telemetry?: ProtonDriveTelemetry,
+    latestEventIdProvider?: LatestEventIdProvider
 };

package/src/interface/nodes.ts

@@ -3,7 +3,7 @@ import { Author } from './author';
 
 /**
  * Node representing a file or folder in the system.
- * 
+ *
  * This covers both happy path and degraded path. It is used in the SDK to
  * represent the node in a way that is easy to work with. Whenever any field
  * cannot be decrypted, it is returned as `DegradedNode` type.
@@ -12,7 +12,7 @@ export type MaybeNode = Result<NodeEntity, DegradedNode>;
 
 /**
  * Node representing a file or folder in the system, or missing node.
- * 
+ *
  * In most cases, SDK returns `MaybeNode`, but in some specific cases, when
  * client is requesting specific nodes, SDK must return `MissingNode` type
  * to indicate the case when the node is not available. That can be when
@@ -27,11 +27,11 @@ export type MissingNode = {
 
 /**
  * Node representing a file or folder in the system.
- * 
+ *
  * This is a happy path representation of the node. It is used in the SDK to
  * represent the node in a way that is easy to work with. Whenever any field
  * cannot be decrypted, it is returned as `DegradedNode` type.
- * 
+ *
  * SDK never returns this entity directly but wrapped in `MaybeNode`.
  *
  * Note on naming: Node is reserved by JS/DOM, thus we need exception how the
@@ -43,7 +43,7 @@ export type NodeEntity = {
     name: string,
     /**
      * Author of the node key.
-     * 
+     *
      * Person who created the node and keys for it. If user A uploads the file
      * and user B renames the file and uploads new revision, name and content
      * author is user B, while key author stays to user A who has forever
@@ -52,7 +52,7 @@ export type NodeEntity = {
     keyAuthor: Author,
     /**
      * Author of the name.
-     * 
+     *
      * Person who named the file. If user A uploads the file and user B renames
      * the file, key and content author is user A, while name author is user B.
      */
@@ -87,20 +87,29 @@ export type NodeEntity = {
     folder?: {
         claimedModificationTime?: Date,
     },
+    /**
+     * Provides an ID for the event scope.
+     *
+     * By subscribing to events in a scope, all updates to nodes
+     * withing that scope will be passed to the client. The scope can
+     * comprise one or more folder trees and will be shared by all
+     * nodes in the tree. Nodes cannot change scopes.
+     */
+    treeEventScopeId: string,
 }
 
 /**
  * Degraded node representing a file or folder in the system.
- * 
+ *
  * This is a degraded path representation of the node. It is used in the SDK to
  * represent the node in a way that is easy to work with. Whenever any field
  * cannot be decrypted, it is returned as `DegradedNode` type.
- * 
+ *
  * SDK never returns this entity directly but wrapped in `MaybeNode`.
- * 
+ *
  * The node can be still used around, but it is not guaranteed that all
  * properties are decrypted, or that all actions can be performed on it.
- * 
+ *
  * For example, if the node has issue decrypting the name, the name will be
  * set as `Error` and potentially rename or move actions will not be
  * possible, but download and upload new revision will still work.
@@ -110,10 +119,10 @@ export type DegradedNode = Omit<NodeEntity, 'name' | 'activeRevision'> & {
     activeRevision?: Result<Revision, Error>,
     /**
      * If the error is not related to any specific field, it is set here.
-     * 
+     *
      * For example, if the node has issue decrypting the name, the name will be
      * set as `Error` while this will be empty.
-     * 
+     *
      * On the other hand, if the node has issue decrypting the node key, but
      * the name is still working, this will include the node key error, while
      * the name will be set to the decrypted value.

package/src/interface/sharing.ts

@@ -36,6 +36,7 @@ export type PublicLink = {
     url: string,
     customPassword?: string,
     expirationTime?: Date,
+    numberOfInitializedDownloads: number
 }
 
 /**

package/src/interface/upload.ts

@@ -24,6 +24,12 @@ export type UploadMetadata = {
      * The metadata will be encrypted and stored with the file.
      */
     additionalMetadata?: object,
+    /**
+     * If there is an existing draft by another client, the upload will be
+     * rejected. If user decides to override the existing draft and continue
+     * with the upload, set this to true.
+     */
+    overrideExistingDraftByOtherClient?: boolean,
 };
 
 export interface FileRevisionUploader {

package/src/internal/download/apiService.ts

@@ -1,5 +1,3 @@
-import { c } from "ttag";
-import { ValidationError } from "../../errors";
 import { DriveAPIService, drivePaths, ObserverStream } from "../apiService";
 import { makeNodeThumbnailUid, splitNodeRevisionUid, splitNodeThumbnailUid } from "../uids";
 import { BlockMetadata } from "./interface";
@@ -85,19 +83,22 @@ export class DownloadAPIService {
         return encryptedBlock;
     }
 
-    // Improvement requested: support multiple volumes.
     async* iterateThumbnails(thumbnailUids: string[], signal?: AbortSignal): AsyncGenerator<
         { uid: string, ok: true, bareUrl: string, token: string } |
         { uid: string, ok: false, error: string }
     > {
-        const thumbnailIds = thumbnailUids.map(splitNodeThumbnailUid);
+        const splitedThumbnailsIds = thumbnailUids.map(splitNodeThumbnailUid);
 
-        const uniqueVolumeIds = new Set(thumbnailIds.map(({ volumeId }) => volumeId));
-        if (uniqueVolumeIds.size !== 1) {
-            throw new ValidationError(c('Error').t`Loading thumbnails from multiple sections is not allowed`);
+        const thumbnailIdsByVolumeId = new Map<string, { volumeId: string, thumbnailId: string, nodeId: string }[]>();
+        for (const { volumeId, thumbnailId, nodeId } of splitedThumbnailsIds) {
+            if (!thumbnailIdsByVolumeId.has(volumeId)) {
+                thumbnailIdsByVolumeId.set(volumeId, []);
+            }
+            thumbnailIdsByVolumeId.get(volumeId)?.push({ volumeId, thumbnailId, nodeId });
         }
-        const volumeId = thumbnailIds[0].volumeId;
 
+
+      for (const [volumeId, thumbnailIds] of thumbnailIdsByVolumeId.entries()) {
         const result = await this.apiService.post<PostGetThumbnailsRequest, PostGetThumbnailsResponse>(
             `drive/volumes/${volumeId}/thumbnails`,
             {
@@ -130,6 +131,8 @@ export class DownloadAPIService {
                 error: error.Error,
             };
         }
+
+      }
     }
 }
 

package/src/internal/download/fileDownloader.ts

@@ -49,7 +49,7 @@ export class FileDownloader {
         return this.revision.claimedSize;
     }
 
-    writeToStream(stream: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController {
+    writeToStream(stream: WritableStream, onProgress?: (downloadedBytes: number) => void): DownloadController {
         if (this.controller.promise) {
             throw new Error(`Download already started`);
         }
@@ -57,7 +57,7 @@ export class FileDownloader {
         return this.controller;
     }
 
-    unsafeWriteToStream(stream: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController {
+    unsafeWriteToStream(stream: WritableStream, onProgress?: (downloadedBytes: number) => void): DownloadController {
         if (this.controller.promise) {
             throw new Error(`Download already started`);
         }