@protontech/drive-sdk 0.0.13 → 0.1.1

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

@@ -2,13 +2,13 @@ import { c } from 'ttag';
 
 /**
  * Base class for all SDK errors.
- * 
+ *
  * This class can be used for catching all SDK errors. The error should have
  * translated message in the `message` property that should be shown to the
  * user without any modification.
- * 
+ *
  * No retries should be done as that is already handled by the SDK.
- * 
+ *
  * When SDK throws an error and it is not `ProtonDriveError`, it is unhandled error
  * by the SDK and usually indicates bug in the SDK. Please, report it.
  */
@@ -18,7 +18,7 @@ export class ProtonDriveError extends Error {
 
 /**
  * Error thrown when the operation is aborted.
- * 
+ *
  * This error is thrown when the operation is aborted by the user.
  * For example, by calling `abort()` on the `AbortSignal`.
  */
@@ -32,7 +32,7 @@ export class AbortError extends ProtonDriveError {
 
 /**
  * Error thrown when the validation fails.
- * 
+ *
  * This error is thrown when the validation of the input fails.
  * Validation can be done on the client side or on the server side.
  *
@@ -45,7 +45,7 @@ export class ValidationError extends ProtonDriveError {
 
     /**
      * Internal API code.
-     * 
+     *
      * Use only for debugging purposes.
      */
     public readonly code?: number;
@@ -64,7 +64,7 @@ export class ValidationError extends ProtonDriveError {
 
 /**
  * Error thrown when the node already exists.
- * 
+ *
  * This error is thrown when the node with the same name already exists in the
  * parent folder. The client should ask the user to replace the existing node
  * or choose another name. The available name is provided in the `availableName`
@@ -75,19 +75,22 @@ 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;
     }
 }
 
 /**
  * Error thrown when the API call fails.
- * 
+ *
  * This error covers both HTTP errors and API errors. SDK automatically
  * retries the request before the error is thrown. The sepcific algorithm
  * used for retries depends on the type of the error.
- * 
+ *
  * Client should not retry the request when this error is thrown.
  */
 export class ServerError extends ProtonDriveError {
@@ -95,13 +98,13 @@ export class ServerError extends ProtonDriveError {
 
     /**
      * HTTP status code of the response.
-     * 
+     *
      * Use only for debugging purposes.
      */
     public readonly statusCode?: number;
     /**
      * Internal API code.
-     * 
+     *
      * Use only for debugging purposes.
      */
     public readonly code?: number;
@@ -109,16 +112,16 @@ export class ServerError extends ProtonDriveError {
 
 /**
  * Error thrown when the client makes too many requests to the API.
- * 
+ *
  * SDK is configured to stay below the rate limits, but it can still happen if
  * client is running multiple SDKs in parallel, or if the rate limits are
  * changed on the server side.
- * 
+ *
  * SDK automatically retries the request before the error is thrown after
  * waiting for the required time specified by the server.
- * 
+ *
  * Client should slow down calling SDK when this error is thrown.
- * 
+ *
  * You can be also notified about the rate limits by the `requestsThrottled`
  * event. See `onMessage` method on the SDK class for more details.
  */
@@ -130,9 +133,9 @@ export class RateLimitedError extends ServerError {
 
 /**
  * Error thrown when the client is not connected to the internet.
- * 
+ *
  * Client should check the internet connection when this error is thrown.
- * 
+ *
  * You can also be notified about the connection status by the `offline` event
  * See `onMessage` method on the SDK class for more details.
  */
@@ -142,9 +145,9 @@ export class ConnectionError extends ProtonDriveError {
 
 /**
  * Error thrown when the decryption fails.
- * 
+ *
  * Client should report this error to the user and report bug report.
- * 
+ *
  * In most cases, there is no decryption error. Every decryption error should
  * be not exposed but set as empty value on the node, for example. But in the
  * case of the file content, if block cannot be decrypted, decryption error
@@ -156,9 +159,9 @@ export class DecryptionError extends ProtonDriveError {
 
 /**
  * Error thrown when the data integrity check fails.
- * 
+ *
  * Client should report this error to the user and report bug report.
- * 
+ *
  * For example, it can happen when hashes don't match, etc. In some cases,
  * SDK allows to run command without verification checks for debug purposes.
  */

package/src/index.ts

@@ -14,12 +14,12 @@ export { VERSION } from './version';
 
 /**
  * Provides the node UID for the given raw volume and node IDs.
- * 
+ *
  * This is required only for the internal implementation to provide
  * backward compatibility with the old Drive web setup.
- * 
+ *
  * If you are having share ID, use `ProtonDriveClient::getNodeUid` instead.
- * 
+ *
  * @deprecated This method is not part of the public API.
  * @param volumeId - Volume of the node.
  * @param nodeId - Node/link ID (not UID).

package/src/interface/account.ts

@@ -6,17 +6,17 @@ export interface ProtonDriveAccount {
      *
      * @throws Error If there is no primary address.
      */
-    getOwnPrimaryAddress(): Promise<ProtonDriveAccountAddress>,
+    getOwnPrimaryAddress(): Promise<ProtonDriveAccountAddress>;
     /**
      * Get own address by email or addressId.
      *
      * @throws Error If there is no address with given email or addressId.
      */
-    getOwnAddress(emailOrAddressId: string): Promise<ProtonDriveAccountAddress>,
+    getOwnAddress(emailOrAddressId: string): Promise<ProtonDriveAccountAddress>;
     /**
      * Returns whether given email can be used to share files with Proton Drive.
      */
-    hasProtonAccount(email: string): Promise<boolean>,
+    hasProtonAccount(email: string): Promise<boolean>;
     /**
      * Get public keys for given email.
      *
@@ -24,15 +24,15 @@ export interface ProtonDriveAccount {
      *
      * @throws Error Only if there is an error while fetching keys.
      */
-    getPublicKeys(email: string): Promise<PublicKey[]>,
+    getPublicKeys(email: string): Promise<PublicKey[]>;
 }
 
 export interface ProtonDriveAccountAddress {
-    email: string,
-    addressId: string,
-    primaryKeyIndex: number,
+    email: string;
+    addressId: string;
+    primaryKeyIndex: number;
     keys: {
-        id: string,
-        key: PrivateKey,
-    }[],
+        id: string;
+        key: PrivateKey;
+    }[];
 }

package/src/interface/author.ts

@@ -2,9 +2,9 @@ import { Result } from './result';
 
 /**
  * Author with verification status.
- * 
+ *
  * It can be either a string (email) or an anonymous user.
- * 
+ *
  * If author cannot be verified, the result is failure with an error.
  * The client can still get claimed author from the error object, but
  * it must be used with caution.
@@ -19,11 +19,11 @@ export type AnonymousUser = null;
 
 /**
  * Unverified author.
- * 
+ *
  * If author cannot be verified, the result is this object containing
  * the claimed author and the verification error.
  */
 export type UnverifiedAuthorError = {
-    claimedAuthor?: string,
-    error: string,
-}
+    claimedAuthor?: string;
+    error: string;
+};

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/devices.ts

@@ -2,15 +2,15 @@ import { Result } from './result';
 import { InvalidNameError } from './nodes';
 
 export type Device = {
-    uid: string,
-    type: DeviceType,
-    name: Result<string, Error | InvalidNameError>,
-    rootFolderUid: string,
-    creationTime: Date,
+    uid: string;
+    type: DeviceType;
+    name: Result<string, Error | InvalidNameError>;
+    rootFolderUid: string;
+    creationTime: Date;
     lastSyncDate?: Date;
     /** @deprecated to be removed once Volume-based navigation is implemented in web */
     shareId: string;
-}
+};
 
 export enum DeviceType {
     Windows = 'Windows',

package/src/interface/download.ts

@@ -1,32 +1,35 @@
 export interface FileDownloader {
     /**
      * Get the claimed size of the file in bytes.
-     * 
+     *
      * This provides total clear-text size of the file. This is encrypted
      * information that is not known to the Proton Drive and thus it is
      * explicitely stated as claimed only and must be treated that way.
      * It can be wrong or missing completely.
      */
-    getClaimedSizeInBytes(): number | undefined,
+    getClaimedSizeInBytes(): number | undefined;
 
     /**
      * Download, decrypt and verify the content from the server and write
      * to the provided stream.
-     * 
+     *
      * @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 {
-    pause(): void,
-    resume(): void,
-    completion(): Promise<void>,
+    pause(): void;
+    resume(): void;
+    completion(): Promise<void>;
 }

package/src/interface/events.ts

@@ -1,30 +1,81 @@
-import { Device } from './devices';
-import { MaybeNode } from './nodes';
-
-export type DeviceEventCallback = (deviceEvent: DeviceEvent) => void;
-export type NodeEventCallback = (nodeEvent: NodeEvent) => void;
-
-export type NodeEvent = {
-    type: 'update',
-    uid: string,
-    node: MaybeNode,
-} | {
-    type: 'remove',
-    uid: string,
+export enum SDKEvent {
+    TransfersPaused = 'transfersPaused',
+    TransfersResumed = 'transfersResumed',
+    RequestsThrottled = 'requestsThrottled',
+    RequestsUnthrottled = 'requestsUnthrottled',
 }
 
-export type DeviceEvent = {
-    type: 'update',
-    uid: string,
-    device: Device,
-} | {
-    type: 'remove',
-    uid: string,
+export interface LatestEventIdProvider {
+    getLatestEventId(treeEventScopeId: string): string | null;
 }
 
-export enum SDKEvent {
-    TransfersPaused = "transfersPaused",
-    TransfersResumed = "transfersResumed",
-    RequestsThrottled = "requestsThrottled",
-    RequestsUnthrottled = "requestsUnthrottled",
+/**
+ * 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>;
+
+export type DriveEvent =
+    | NodeEvent
+    | FastForwardEvent
+    | TreeRefreshEvent
+    | TreeRemovalEvent
+    | FastForwardEvent
+    | SharedWithMeUpdated;
+
+export type NodeEvent =
+    | {
+          type: DriveEventType.NodeCreated | DriveEventType.NodeUpdated;
+          nodeUid: string;
+          parentNodeUid?: string;
+          isTrashed: boolean;
+          isShared: boolean;
+          treeEventScopeId: string;
+          eventId: string;
+      }
+    | {
+          type: DriveEventType.NodeDeleted;
+          nodeUid: string;
+          parentNodeUid?: string;
+          treeEventScopeId: string;
+          eventId: string;
+      };
+
+export type FastForwardEvent = {
+    type: DriveEventType.FastForward;
+    treeEventScopeId: string;
+    eventId: string;
+};
+
+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 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',
 }