@protontech/drive-sdk 0.0.10

package/dist/transformers.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUid = getUid;
+exports.getUids = getUids;
+exports.convertInternalNodeIterator = convertInternalNodeIterator;
+exports.convertInternalMissingNodeIterator = convertInternalMissingNodeIterator;
+exports.convertInternalNodePromise = convertInternalNodePromise;
+exports.convertInternalNode = convertInternalNode;
+const interface_1 = require("./interface");
+function getUid(nodeUid) {
+    if (typeof nodeUid === "string") {
+        return nodeUid;
+    }
+    // Directly passed NodeEntity or DegradedNode that has UID directly.
+    if ('uid' in nodeUid) {
+        return nodeUid.uid;
+    }
+    // MaybeNode that can be either NodeEntity or DegradedNode.
+    if (nodeUid.ok) {
+        return nodeUid.value.uid;
+    }
+    return nodeUid.error.uid;
+}
+function getUids(nodeUids) {
+    return nodeUids.map(getUid);
+}
+async function* convertInternalNodeIterator(nodeIterator) {
+    for await (const node of nodeIterator) {
+        yield convertInternalNode(node);
+    }
+}
+async function* convertInternalMissingNodeIterator(nodeIterator) {
+    for await (const node of nodeIterator) {
+        if ('missingUid' in node) {
+            yield (0, interface_1.resultError)(node);
+        }
+        else {
+            yield convertInternalNode(node);
+        }
+    }
+}
+async function convertInternalNodePromise(nodePromise) {
+    const node = await nodePromise;
+    return convertInternalNode(node);
+}
+function convertInternalNode(node) {
+    const baseNodeMetadata = {
+        uid: node.uid,
+        parentUid: node.parentUid,
+        keyAuthor: node.keyAuthor,
+        nameAuthor: node.nameAuthor,
+        directMemberRole: node.directMemberRole,
+        type: node.type,
+        mediaType: node.mediaType,
+        isShared: node.isShared,
+        creationTime: node.creationTime,
+        trashTime: node.trashTime,
+        totalStorageSize: node.totalStorageSize,
+        folder: node.folder,
+    };
+    const name = node.name;
+    const activeRevision = node.activeRevision;
+    if (node.errors?.length || !name.ok || (activeRevision && !activeRevision.ok)) {
+        return (0, interface_1.resultError)({
+            ...baseNodeMetadata,
+            name,
+            activeRevision,
+            errors: node.errors,
+        });
+    }
+    return (0, interface_1.resultOk)({
+        ...baseNodeMetadata,
+        name: name.value,
+        activeRevision: activeRevision?.value,
+    });
+}
+//# sourceMappingURL=transformers.js.map

package/dist/transformers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers.js","sourceRoot":"","sources":["../src/transformers.ts"],"names":[],"mappings":";;AAwBA,wBAaC;AAED,0BAEC;AAED,kEAIC;AAED,gFAQC;AAED,gEAGC;AAED,kDAiCC;AAjGD,2CAAuN;AAwBvN,SAAgB,MAAM,CAAC,OAAgB;IACnC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC;IACnB,CAAC;IACD,oEAAoE;IACpE,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;QACnB,OAAO,OAAO,CAAC,GAAG,CAAC;IACvB,CAAC;IACD,2DAA2D;IAC3D,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;IAC7B,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;AAC7B,CAAC;AAED,SAAgB,OAAO,CAAC,QAAmB;IACvC,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAEM,KAAK,SAAU,CAAC,CAAA,2BAA2B,CAAC,YAAiD;IAChG,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QACpC,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;AACL,CAAC;AAEM,KAAK,SAAU,CAAC,CAAA,kCAAkC,CAAC,YAA+D;IACrH,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QACpC,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,IAAA,uBAAW,EAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACJ,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;IACL,CAAC;AACL,CAAC;AAEM,KAAK,UAAU,0BAA0B,CAAC,WAAyC;IACtF,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC;IAC/B,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,SAAgB,mBAAmB,CAAC,IAAyB;IACzD,MAAM,gBAAgB,GAAG;QACrB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,MAAM,EAAE,IAAI,CAAC,MAAM;KACtB,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;IAE3C,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,cAAc,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5E,OAAO,IAAA,uBAAW,EAAC;YACf,GAAG,gBAAgB;YACnB,IAAI;YACJ,cAAc;YACd,MAAM,EAAE,IAAI,CAAC,MAAM;SACA,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,IAAA,oBAAQ,EAAC;QACZ,GAAG,gBAAgB;QACnB,IAAI,EAAE,IAAI,CAAC,KAAK;QAChB,cAAc,EAAE,cAAc,EAAE,KAAK;KACpB,CAAC,CAAC;AAC3B,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+const package_json_1 = require("../package.json");
+exports.VERSION = package_json_1.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AAAA,kDAA0C;AAE7B,QAAA,OAAO,GAAG,sBAAO,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@protontech/drive-sdk",
+    "version": "0.0.10",
+    "description": "Proton Drive SDK",
+    "license": "GPL-3.0",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "build:ci": "rm -rf dist && tsc",
+        "check-types": "tsc --noEmit",
+        "generate-doc:interface": "typedoc src/index.ts --out ${OUTPUT_PATH}",
+        "generate-doc:internal": "typedoc src/**/*.ts --out ${OUTPUT_PATH}",
+        "generate-types": "openapi-typescript ../../api/openapi-drive.json -o ./src/internal/apiService/driveTypes.ts && openapi-typescript ../../api/openapi-core.json -o ./src/internal/apiService/coreTypes.ts",
+        "lint": "eslint src --ext .ts --cache --ignore-pattern '**/apiService/*Types.ts'",
+        "pretty": "prettier --write  $(find src -type f -name '*.ts')",
+        "test": "jest",
+        "test:ci": "jest --runInBand --no-cache",
+        "test:watch": "jest --watch --coverage=false",
+        "lint:ttag": "node tasks/linter.mjs src --verbose",
+        "extract:ttag": "ttag extract src --output po/template.pot"
+    },
+    "dependencies": {
+        "@noble/hashes": "^1.8.0",
+        "bcryptjs": "^2.4.3",
+        "ttag": "^1.8.7"
+    },
+    "devDependencies": {
+        "@swc/core": "^1.12.3",
+        "@swc/jest": "^0.2.38",
+        "@types/jest": "^29.5.14",
+        "@types/mocha": "^10.0.10",
+        "@typescript-eslint/eslint-plugin": "^8.19.1",
+        "@web/dev-server-esbuild": "^1.0.3",
+        "eslint": "^8.57.1",
+        "eslint-plugin-tsdoc": "^0.3.0",
+        "glob": "^11.0.3",
+        "jest": "^29.7.0",
+        "openapi-typescript": "^7.4.1",
+        "prettier": "^3.4.2",
+        "ttag-cli": "^1.10.18",
+        "typedoc": "^0.26.11",
+        "typescript": "^5.6.3"
+    }
+}

package/src/cache/index.ts

@@ -0,0 +1,2 @@
+export type { ProtonDriveCache, EntityResult } from './interface';
+export { MemoryCache } from './memoryCache';

package/src/cache/interface.ts

@@ -0,0 +1,104 @@
+export interface ProtonDriveCacheConstructor<T> {
+    /**
+     * Initialize the cache.
+     * 
+     * The local database should follow document-based structure. The SDK does
+     * serialisation and data is not intended to be read by 3rd party. The SDK,
+     * however, provides also clear fields in form of tags that is used for
+     * search. Local database should have index or other structure for easier
+     * look-up.
+     * 
+     * See {@link setEntity} for more details how tags are used.
+     */
+     new (): ProtonDriveCache<T>,
+}
+
+export interface ProtonDriveCache<T> {
+    /**
+     * Re-creates the whole persistent cache.
+     * 
+     * The SDK can call this when there is some inconsistency and it is better
+     * to start from scratch rather than fix it.
+     */
+    clear(): Promise<void>,
+
+    /**
+     * Adds or updates entity in the local database.
+     * 
+     * The `tags` is a list of strings that should be stored properly for fast
+     * look-up.
+     * 
+     * @example Usage by the SDK
+     * ```ts
+     * await cache.setEntity("node-abc42", "{ node abc42 serialised data }", ["parentUid:abc123", "sharedWithMe"] });
+     * await Array.fromAsync(cache.iterateEntitiesByTag("parentUid:abc123")); // returns ["node-abc42"]
+     * await cache.getEntity("node-abc42"); // returns "{ node abc42 serialised data }"
+     * await Array.fromAsync(cache.iterateEntities(["node-abc42"])); // returns ["{ node abc42 serialised data }"]
+     * ```
+     * 
+     * @example Stored data
+     * ```json
+     * {
+     *     type: "node",
+     *     version: 1,
+     *     internal: {
+     *         isStale,
+     *         claimedDigests,
+     *         // ...
+     *     }
+     *     node: {
+     *         // same as node entity, here some example
+     *         uid,
+     *         parentUid,
+     *         // ...
+     *     }
+     * }
+     * ```
+     * 
+     * @param key - Key is internal ID controlled by the SDK. It combines type and ID of the entity.
+     * @param value - Serialised JSON object controlled by the SDK. It is not intended for use outside of the SDK.
+     * @param tags - Clear metadata about the entity used for filtering. It is intended to store efficiently for fast look-up.
+     * @throws Exception if `key` from `tags` is not one of the tag keys provided from `usedTagKeysBySDK` in constructor.
+     */
+    setEntity(key: string, value: T, tags?: string[] ): Promise<void>,
+    
+    /**
+     * Returns the data of the entity stored locally.
+     * 
+     * @throws Exception if entity is not present.
+     */
+    getEntity(key: string): Promise<T>,
+
+    /**
+     * Generator providing the data of the entities stored locally for given
+     * list of keys.
+     * 
+     * No exception is thrown when data is missing.
+     */
+    iterateEntities(keys: string[]): AsyncGenerator<EntityResult<T>>,
+
+    /**
+     * Generator providing the data of the entities stored locally for given
+     * filter option.
+     * 
+     * No exception is thrown when data is missing.
+     * 
+     * @example Usage by the SDK
+     * ```ts
+     * await cache.setEntity("node-abc42", "{ node abc42 serialised data }", { "parentUid": "abc123", "shared": "withMe" });
+     * await Array.fromAsync(cache.iterateEntitiesByTag("parentUid", "abc123")); // returns ["node-abc42"]
+     * ```
+     * 
+     * @param tag - The tag, for example `parentUid:abc123`
+     */
+    iterateEntitiesByTag(tag: string): AsyncGenerator<EntityResult<T>>,
+
+    /**
+     * Removes completely the entity stored locally from the database.
+     * 
+     * It is no-op if entity is not present.
+     */
+    removeEntities(keys: string[]): Promise<void>,
+}
+
+export type EntityResult<T> = {key: string, ok: true, value: T} | {key: string, ok: false, error: string};

package/src/cache/memoryCache.test.ts

@@ -0,0 +1,150 @@
+import { EntityResult } from "./interface";
+import { MemoryCache } from "./memoryCache";
+
+describe('MemoryCache', () => {
+    let cache: MemoryCache<string>;
+
+    beforeEach(async () => {
+        cache = new MemoryCache();
+
+        await cache.setEntity('key1', 'value1', ['tag1:hello', 'tag2:world']);
+        await cache.setEntity('key2', 'value2', ['tag2:world']);
+        await cache.setEntity('key3', 'value3');
+    });
+
+    it('should store and retrieve an entity', async () => {
+        const key = 'newkey';
+        const value = 'newvalue';
+
+        await cache.setEntity(key, value);
+        const result = await cache.getEntity(key);
+
+        expect(result).toBe(value);
+    });
+
+    it('should update an entity with tags - remove old and add new tags', async () => {
+        const key = 'newkey';
+
+        await cache.setEntity(key, 'value1', ['tag1', 'tag2']);
+        await cache.setEntity(key, 'value2', ['tag2', 'tag3']);
+
+        const result = await cache.getEntity(key);
+        expect(result).toBe('value2');
+
+        const tag1 = await Array.fromAsync(cache.iterateEntitiesByTag('tag1'));
+        expect(tag1).toEqual([]);
+        const tag2 = await Array.fromAsync(cache.iterateEntitiesByTag('tag2'));
+        expect(tag2).toEqual([{ key, ok: true, value: 'value2' }]);
+        const tag3 = await Array.fromAsync(cache.iterateEntitiesByTag('tag3'));
+        expect(tag3).toEqual([{ key, ok: true, value: 'value2' }]);
+    });
+
+    it('should throw an error when retrieving a non-existing entity', async () => {
+        const key = 'newkey';
+
+        try {
+            await cache.getEntity(key);
+            fail('Should have thrown an error');
+        } catch (error) {
+            expect(`${error}`).toBe('Error: Entity not found');
+        }
+    });
+
+    it('should iterate over entities', async () => {
+        const results = [];
+        for await (const result of cache.iterateEntities(['key1', 'key2', 'key100'])) {
+            results.push(result);
+        }
+
+        expect(results).toEqual([
+            { key: 'key1', ok: true, value: 'value1' },
+            { key: 'key2', ok: true, value: 'value2' },
+            { key: 'key100', ok: false, error: 'Error: Entity not found' },
+        ]);
+    });
+
+    it('should iterate over entities by tag', async () => {
+        const results = [];
+        for await (const result of cache.iterateEntitiesByTag('tag2:world')) {
+            results.push(result);
+        }
+
+        expect(results).toEqual([
+            { key: 'key1', ok: true, value: 'value1' },
+            { key: 'key2', ok: true, value: 'value2' },
+        ]);
+    });
+
+    it('should iterate over entities with multiple tags by tag', async () => {
+        const results = [];
+        for await (const result of cache.iterateEntitiesByTag('tag1:hello')) {
+            results.push(result);
+        }
+
+        expect(results).toEqual([
+            { key: 'key1', ok: true, value: 'value1' },
+        ]);
+    });
+
+    it('should iterate over entities by empty tag', async () => {
+        const results = [];
+        for await (const result of cache.iterateEntitiesByTag('nonexistent')) {
+            results.push(result);
+        }
+
+        expect(results).toEqual([]);
+    });
+
+    it('should iterate over entities with concurrent changes to the same set', async () => {
+        const iterator = cache.iterateEntities(['key1', 'key2', 'key3']);
+        
+        const results: string[] = [];
+        const { value: { key: key1 } } = await iterator.next();
+        results.push(key1);
+        await cache.removeEntities([key1]);
+
+        let value = await iterator.next(); // key2
+        results.push(value.value.key);
+
+        value = await iterator.next(); // key3
+        results.push(value.value.key);
+
+        expect(results).toEqual(['key1', 'key2', 'key3']);
+    });
+
+    it('should remove entities', async () => {
+        await cache.removeEntities(['key1', 'key3']);
+
+        const results = [];
+        for await (const result of cache.iterateEntities(['key1', 'key2', 'key3'])) {
+            results.push(result);
+        }
+
+        expect(results).toEqual([
+            { key: 'key1', ok: false, error: 'Error: Entity not found' },
+            { key: 'key2', ok: true, value: 'value2' },
+            { key: 'key3', ok: false, error: 'Error: Entity not found' },
+        ]);
+
+        const results2 = [];
+        for await (const result of cache.iterateEntitiesByTag('tag1:hello')) {
+            results2.push(result);
+        }
+        expect(results2).toEqual([]);
+    });
+
+    it('should clear the cache', async () => {
+        await cache.clear();
+
+        const results = [];
+        for await (const result of cache.iterateEntities(['key1', 'key2', 'key3'])) {
+            results.push(result);
+        }
+
+        expect(results).toEqual([
+            { key: 'key1', ok: false, error: 'Error: Entity not found' },
+            { key: 'key2', ok: false, error: 'Error: Entity not found' },
+            { key: 'key3', ok: false, error: 'Error: Entity not found' },
+        ]);
+    });
+});

package/src/cache/memoryCache.ts

@@ -0,0 +1,85 @@
+import type { ProtonDriveCache, EntityResult } from './interface';
+
+type KeyValueCache<T> = { [ key: string ]: T };
+type TagsCache = { [ tag: string ]: string[] };
+
+/**
+ * In-memory cache implementation for Proton Drive SDK.
+ * 
+ * This cache is not persistent and is intended for mostly for testing or
+ * development only. It is not recommended to use this cache in production
+ * environments.
+ */
+export class MemoryCache<T> implements ProtonDriveCache<T> {
+    private entities: KeyValueCache<T> = {};
+    private entitiesByTag: TagsCache = {};
+
+    async clear() {
+        this.entities = {};
+    }
+
+    async setEntity(key: string, value: T, tags?: string[]) {
+        this.entities[key] = value;
+
+        for (const tag of Object.keys(this.entitiesByTag)) {
+            const index = this.entitiesByTag[tag].indexOf(key);
+            if (index !== -1) {
+                this.entitiesByTag[tag].splice(index, 1);
+                if (this.entitiesByTag[tag].length === 0) {
+                    delete this.entitiesByTag[tag];
+                }
+            }
+        }
+
+        if (tags) {
+            for (const tag of tags) {
+                if (!this.entitiesByTag[tag]) {
+                    this.entitiesByTag[tag] = [];
+                }
+                this.entitiesByTag[tag].push(key);
+            }
+        }
+    }
+
+    async getEntity(key: string) {
+        const value = this.entities[key];
+        if (!value) {
+            throw Error('Entity not found');
+        }
+        return value;
+    }
+
+    async *iterateEntities(keys: string[]): AsyncGenerator<EntityResult<T>> {
+        for (const key of keys) {
+            try {
+                const value = await this.getEntity(key);
+                yield { key, ok: true, value };
+            } catch (error) {
+                yield { key, ok: false, error: `${error}` };
+            }
+        }
+    }
+
+    async *iterateEntitiesByTag(tag: string): AsyncGenerator<EntityResult<T>> {
+        const keys = this.entitiesByTag[tag];
+        if (!keys) {
+            return;
+        }
+
+        // Pass copy of keys so concurrent changes to the cache do not affect
+        // results from iterating entities.
+        yield* this.iterateEntities([...keys]);
+    }
+
+    async removeEntities(keys: string[]) {
+        for (const key of keys) {
+            delete this.entities[key];
+            Object.values(this.entitiesByTag).forEach((tagKeys) => {
+                const index = tagKeys.indexOf(key);
+                if (index !== -1) {
+                    tagKeys.splice(index, 1);
+                }
+            });
+        }
+    }
+};

package/src/config.ts

@@ -0,0 +1,9 @@
+import { ProtonDriveConfig } from './interface';
+
+export function getConfig(config?: ProtonDriveConfig): Required<ProtonDriveConfig> {
+    return {
+        ...config,
+        baseUrl: config?.baseUrl ? `https://${config.baseUrl}` : 'https://drive-api.proton.me',
+        language: config?.language || 'en',
+    };
+}

package/src/crypto/driveCrypto.test.ts

@@ -0,0 +1,45 @@
+import { uint8ArrayToUtf8, arrayToHexString } from "./driveCrypto";
+
+describe("uint8ArrayToUtf8", () => {
+    it("should convert a Uint8Array to a UTF-8 string", () => {
+        const input = new Uint8Array([72, 101, 108, 108, 111]);
+        const expectedOutput = "Hello";
+        const result = uint8ArrayToUtf8(input);
+        expect(result).toBe(expectedOutput);
+    });
+
+    it("should handle an empty Uint8Array", () => {
+        const input = new Uint8Array([]);
+        const expectedOutput = "";
+        const result = uint8ArrayToUtf8(input);
+        expect(result).toBe(expectedOutput);
+    });
+
+    it("should throw if input is invalid", () => {
+        const input = new Uint8Array([887987979887897989]);
+        expect(() => uint8ArrayToUtf8(input)).toThrow("The encoded data was not valid for encoding utf-8");
+    });
+});
+
+describe("arrayToHexString", () => {
+    it("should convert a Uint8Array to a hex string", () => {
+        const input = new Uint8Array([0, 255, 16, 32]);
+        const expectedOutput = "00ff1020";
+        const result = arrayToHexString(input);
+        expect(result).toBe(expectedOutput);
+    });
+
+    it("should handle an empty Uint8Array", () => {
+        const input = new Uint8Array([]);
+        const expectedOutput = "";
+        const result = arrayToHexString(input);
+        expect(result).toBe(expectedOutput);
+    });
+
+    it("should handle a Uint8Array with one element", () => {
+        const input = new Uint8Array([1]);
+        const expectedOutput = "01";
+        const result = arrayToHexString(input);
+        expect(result).toBe(expectedOutput);
+    });
+});