@protontech/drive-sdk 0.0.10

package/src/protonDrivePhotosClient.ts

@@ -0,0 +1,56 @@
+import { DriveAPIService } from './internal/apiService';
+import { ProtonDriveClientContructorParameters } from './interface';
+import { DriveCrypto } from './crypto';
+import { initSharesModule } from './internal/shares';
+import { initNodesModule } from './internal/nodes';
+import { initPhotosModule } from './internal/photos';
+import { DriveEventsService } from './internal/events';
+import { SDKEvents } from './internal/sdkEvents';
+import { getConfig } from './config';
+import { Telemetry } from './telemetry';
+
+// TODO: this is only example, on background it use drive internals, but it exposes nice interface for photos
+export class ProtonDrivePhotosClient {
+    private nodes: ReturnType<typeof initNodesModule>;
+    private photos: ReturnType<typeof initPhotosModule>;
+
+    constructor({
+        httpClient,
+        entitiesCache,
+        cryptoCache,
+        account,
+        openPGPCryptoModule,
+        srpModule,
+        config,
+        telemetry,
+    }: ProtonDriveClientContructorParameters) {
+        if (!telemetry) {
+            telemetry = new Telemetry();
+        }
+
+        const fullConfig = getConfig(config);
+        const sdkEvents = new SDKEvents(telemetry);
+        const cryptoModule = new DriveCrypto(openPGPCryptoModule, srpModule);
+        const apiService = new DriveAPIService(telemetry, sdkEvents, httpClient, fullConfig.baseUrl, fullConfig.language);
+        const events = new DriveEventsService(telemetry, apiService, entitiesCache);
+        const shares = initSharesModule(telemetry, apiService, entitiesCache, cryptoCache, account, cryptoModule);
+        this.nodes = initNodesModule(telemetry, apiService, entitiesCache, cryptoCache, account, cryptoModule, events, shares);
+        this.photos = initPhotosModule(apiService, entitiesCache, this.nodes.access);
+    }
+
+    // Timeline or album view
+    iterateTimelinePhotos() { } // returns only UIDs and dates - used to show grid and scrolling
+    iterateAlbumPhotos() { } // same as above but for album
+    iterateThumbnails() { } // returns thumbnails for passed photos that are visible in the UI
+    getPhoto() { } // returns full photo details
+
+    // Album management
+    createAlbum(albumName: string) {
+        return this.photos.albums.createAlbum(albumName);
+    }
+    renameAlbum() { }
+    shareAlbum() { }
+    deleteAlbum() { }
+    iterateAlbums() { }
+    addPhotosToAlbum() { }
+}

package/src/telemetry.ts

@@ -0,0 +1,346 @@
+import { Logger as LoggerInterface } from './interface';
+
+export interface LogRecord {
+    time: Date,
+    level: LogLevel;
+    loggerName: string;
+    message: string;
+    error?: unknown;
+}
+
+export enum LogLevel {
+    DEBUG = 'DEBUG',
+    INFO = 'INFO',
+    WARNING = 'WARNING',
+    ERROR = 'ERROR',
+}
+
+export interface LogFormatter {
+    format(log: LogRecord): string;
+}
+
+export interface LogHandler {
+    log(log: LogRecord): void;
+}
+
+export interface MetricRecord<T extends MetricEvent> {
+    time: Date,
+    event: T;
+}
+
+export type MetricEvent = {
+    eventName: string;
+}
+
+export interface MetricHandler<T extends MetricEvent> {
+    onEvent(metric: MetricRecord<T>): void;
+}
+
+/**
+ * Telemetry class that logs messages and metrics.
+ * 
+ * Example:
+ * 
+ * ```typescript
+ * const memoryLogHandler = new MemoryLogHandler();
+ * 
+ * interface MetricEvents = {
+ *    name: string,
+ *    value: number,
+ * }
+ * class OwnMetricHandler implements MetricHandler<MetricEvents> {
+ *    onEvent(metric: MetricRecord<MetricEvents>) {
+ *        // Process metric event
+ *    }
+ * }
+ * 
+ * const telemetry = new Telemetry<MetricEvents>({
+ *    // Enable debug logging
+ *    logFilter: new LogFilter({ level: LogLevel.DEBUG }),
+ *    // Log to console and memory
+ *    logHandlers: [new ConsoleLogHandler(), memoryLogHandler],
+ *    // Log to console and own handler to process further
+ *    metricHandlers: [new ConsoleMetricHandler(), ownMetricHandler],
+ * });
+ * 
+ * const logger = telemetry.getLogger('myLogger');
+ * logger.debug('Debug message');
+ * 
+ * telemetry.logEvent({ name: 'somethingHappened', value: 42 });
+ * 
+ * const logs = memoryLogHandler.getLogs();
+ * // Process logs
+ * ```
+ * 
+ * @param logFilter - Log filter to filter logs based on log level, default INFO
+ * @param logHandlers - Log handlers to use for logging, see LogHandler implementations
+ * @param metricHandlers - Metric handlers to use for logging, see MetricHandler implementations
+ */
+export class Telemetry<T extends MetricEvent> {
+    private logFilter: LogFilter;
+    private logHandlers: LogHandler[];
+    private metricHandlers: MetricHandler<T>[];
+
+    constructor(
+        options?: {
+            logFilter?: LogFilter,
+            logHandlers?: LogHandler[],
+            metricHandlers?: MetricHandler<T>[],
+        }
+    ) {
+        this.logFilter = options?.logFilter || new LogFilter();
+        this.logHandlers = options?.logHandlers || [new ConsoleLogHandler()];
+        this.metricHandlers = options?.metricHandlers || [new ConsoleMetricHandler()];
+    }
+
+    getLogger(name: string): Logger {
+        return new Logger(name, this.logFilter, this.logHandlers);
+    }
+
+    logEvent(event: T): void {
+        const metric = {
+            time: new Date(),
+            event,
+        };
+        this.metricHandlers.forEach(handler => handler.onEvent(metric));
+    }
+}
+
+/**
+ * Logger class that logs messages with different levels.
+ * 
+ * @param name - Name of the logger
+ * @param handlers - Log handlers to use for logging, see LogHandler implementations
+ */
+class Logger {
+    constructor(private name: string, private filter: LogFilter, private handlers: LogHandler[]) {
+        this.name = name;
+        this.filter = filter;
+        this.handlers = handlers;
+    }
+
+    debug(message: string) {
+        this.log({
+            time: new Date(),
+            level: LogLevel.DEBUG,
+            loggerName: this.name,
+            message,
+        });
+    }
+
+    info(message: string) {
+        this.log({
+            time: new Date(),
+            level: LogLevel.INFO,
+            loggerName: this.name,
+            message,
+        });
+    }
+
+    warn(message: string) {
+        this.log({
+            time: new Date(),
+            level: LogLevel.WARNING,
+            loggerName: this.name,
+            message,
+        });
+    }
+
+    error(message: string, error?: unknown) {
+        this.log({
+            time: new Date(),
+            level: LogLevel.ERROR,
+            loggerName: this.name,
+            message,
+            error,
+        });
+    }
+
+    private log(log: LogRecord) {
+        if (!this.filter.filter(log)) {
+            return;
+        }
+        this.handlers.forEach(handler => handler.log(log));
+    }
+}
+
+/**
+ * Logger class that logs messages with a prefix.
+ * 
+ * Example:
+ * 
+ * ```typescript
+ * const logger = new Logger('myLogger', new LogFilter(), [new ConsoleLogHandler()]);
+ * const loggerWithPrefix = new LoggerWithPrefix(logger, 'prefix');
+ * loggerWithPrefix.info('Info message');
+ * ```
+ */
+export class LoggerWithPrefix {
+    constructor(private logger: LoggerInterface, private prefix: string) {
+        this.logger = logger;
+        this.prefix = prefix;
+    }
+
+    info(message: string) {
+        this.logger.info(`${this.prefix}: ${message}`);
+    }
+
+    debug(message: string) {
+        this.logger.debug(`${this.prefix}: ${message}`);
+    }
+
+    warn(message: string) {
+        this.logger.warn(`${this.prefix}: ${message}`);
+    }
+
+    error(message: string, error?: unknown) {
+        this.logger.error(`${this.prefix}: ${message}`, error);
+    }
+}
+
+/**
+ * Filter logs based on log level. It can be configured by global level or
+ * per logger level.
+ * 
+ * @param globalLevel - Global log level, default INFO
+ * @param loggerLevels - Log levels for specific loggers, default empty
+ */
+export class LogFilter {
+    private logLevelMap = {
+        'DEBUG': 0,
+        'INFO': 1,
+        'WARNING': 2,
+        'ERROR': 3,
+    }
+
+    private globalLevel: number;
+    private loggerLevels: { [loggerName: string]: number };
+
+    constructor(options?: {
+        globalLevel?: LogLevel,
+        loggerLevels?: { [loggerName: string]: LogLevel },
+    }) {
+        this.globalLevel = this.logLevelMap[options?.globalLevel || LogLevel.INFO];
+        this.loggerLevels = Object.fromEntries(Object.entries(options?.loggerLevels || {})
+            .map(([loggerName, level]) => [loggerName, this.logLevelMap[level]]));
+    }
+
+    /**
+     * @returns False if the log should be ignored.
+     */
+    filter(log: LogRecord) {
+        const logLevel = this.logLevelMap[log.level];
+        if (logLevel < this.globalLevel) {
+            return false;
+        }
+        const loggerLevel = this.loggerLevels[log.loggerName] || 0;
+        if (logLevel < loggerLevel) {
+            return false;
+        }
+        return true;
+    }
+}
+
+/**
+ * Log handler that logs to console.
+ * 
+ * @param formatter - Formatter to use for log messages, default BasicLogFormatter
+ */
+export class ConsoleLogHandler implements LogHandler {
+    private logLevelMap = {
+        'DEBUG': console.debug, // eslint-disable-line no-console
+        'INFO': console.info, // eslint-disable-line no-console
+        'WARNING': console.warn, // eslint-disable-line no-console
+        'ERROR': console.error, // eslint-disable-line no-console
+    }
+
+    private formatter: LogFormatter;
+
+    constructor(formatter?: LogFormatter) {
+        this.formatter = formatter || new BasicLogFormatter();
+    }
+
+    log(log: LogRecord) {
+        const message = this.formatter.format(log);
+        this.logLevelMap[log.level](message);
+    }
+}
+
+/**
+ * Log handler that stores logs in memory with option to retrieve later.
+ * 
+ * Useful for keeping logs around and retrieve them on demand when an error
+ * occures.
+ * 
+ * @param formatter - Formatter to use for log messages, default JSONLogFormatter
+ * @param maxLogs - Maximum number of logs to store, default 10000
+ */
+export class MemoryLogHandler implements LogHandler {
+    private logs: string[] = [];
+
+    private formatter: LogFormatter;
+
+    constructor(formatter?: LogFormatter, private maxLogs = 10000) {
+        this.formatter = formatter || new JSONLogFormatter();
+        this.maxLogs = maxLogs;
+    }
+
+    log(log: LogRecord) {
+        const message = this.formatter.format(log);
+        this.logs.push(message);
+
+        if (this.logs.length > this.maxLogs) {
+            this.logs.shift();
+        }
+    }
+
+    getLogs() {
+        return this.logs;
+    }
+
+    clear() {
+        this.logs = [];
+    }
+}
+
+/**
+ * Formatter that formats logs as JSON.
+ * 
+ * Useful for machine processing.
+ */
+export class JSONLogFormatter implements LogFormatter {
+    format(log: LogRecord) {
+        if (log.error instanceof Error) {
+            return JSON.stringify({
+                ...log,
+                error: log.error.message,
+                stack: log.error.stack,
+            });
+        }
+        return JSON.stringify(log);
+    }
+}
+
+/**
+ * Formatter that formats logs as plain text.
+ * 
+ * Useful for human reading.
+ */
+export class BasicLogFormatter implements LogFormatter {
+    format(log: LogRecord) {
+        let errorDetails = '';
+        if (log.error) {
+            errorDetails = log.error instanceof Error
+                ? `\nError: ${log.error.message}\nStack:\n${log.error.stack}`
+                : `\nError: ${log.error}`;
+        }
+        return `${log.time.toISOString()} ${log.level} [${log.loggerName}] ${log.message}${errorDetails}`;
+    }
+}
+
+class ConsoleMetricHandler<T extends MetricEvent> implements MetricHandler<T> {
+    onEvent(metric: MetricRecord<T>) {
+        // eslint-disable-next-line no-console
+        console.info(`${metric.time.toISOString()} INFO [metric] ${metric.event.eventName} ${JSON.stringify({ ...metric.event, name: undefined })}`);
+    }
+}

package/src/tests/logger.ts

@@ -0,0 +1,10 @@
+import { Logger } from '../interface';
+
+export function getMockLogger(): Logger {
+    return {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    }
+}

package/src/tests/telemetry.ts

@@ -0,0 +1,9 @@
+import { ProtonDriveTelemetry } from "../interface";
+import { getMockLogger } from "./logger";
+
+export function getMockTelemetry(): ProtonDriveTelemetry {
+    return {
+        getLogger: getMockLogger,
+        logEvent: jest.fn(),
+    };
+}

package/src/transformers.ts

@@ -0,0 +1,98 @@
+import { MaybeNode as PublicMaybeNode, MaybeMissingNode as PublicMaybeMissingNode, NodeEntity as PublicNodeEntity, DegradedNode as PublicDegradedNode, Result, resultOk, resultError, MissingNode } from './interface';
+import { DecryptedNode as InternalNode } from './internal/nodes';
+
+type InternalPartialNode = Pick<
+    InternalNode,
+    'uid' |
+    'parentUid' |
+    'name' |
+    'keyAuthor' |
+    'nameAuthor' |
+    'directMemberRole' |
+    'type' |
+    'mediaType' |
+    'isShared' |
+    'creationTime' |
+    'trashTime' |
+    'activeRevision' |
+    'folder' |
+    'totalStorageSize' |
+    'errors'
+>;
+
+type NodeUid = string | { uid: string } | Result<{ uid: string }, { uid: string }>;
+
+export function getUid(nodeUid: NodeUid): string {
+    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;
+}
+
+export function getUids(nodeUids: NodeUid[]): string[] {
+    return nodeUids.map(getUid);
+}
+
+export async function *convertInternalNodeIterator(nodeIterator: AsyncGenerator<InternalPartialNode>): AsyncGenerator<PublicMaybeNode> {
+    for await (const node of nodeIterator) {
+        yield convertInternalNode(node);
+    }
+}
+
+export async function *convertInternalMissingNodeIterator(nodeIterator: AsyncGenerator<InternalPartialNode | MissingNode>): AsyncGenerator<PublicMaybeMissingNode> {
+    for await (const node of nodeIterator) {
+        if ('missingUid' in node) {
+            yield resultError(node);
+        } else {
+            yield convertInternalNode(node);
+        }
+    }
+}
+
+export async function convertInternalNodePromise(nodePromise: Promise<InternalPartialNode>): Promise<PublicMaybeNode> {
+    const node = await nodePromise;
+    return convertInternalNode(node);
+}
+
+export function convertInternalNode(node: InternalPartialNode): PublicMaybeNode {
+    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 resultError({
+            ...baseNodeMetadata,
+            name,
+            activeRevision,
+            errors: node.errors,
+        } as PublicDegradedNode);
+    }
+
+    return resultOk({
+        ...baseNodeMetadata,
+        name: name.value,
+        activeRevision: activeRevision?.value,
+    } as PublicNodeEntity);
+}

package/src/version.ts

@@ -0,0 +1,4 @@
+import { version } from '../package.json';
+
+export const VERSION = version;
+