@protontech/drive-sdk 0.0.10

package/dist/interface/nodes.d.ts

@@ -0,0 +1,161 @@
+import { Result } from './result';
+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.
+ */
+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
+ * the node does not exist, or when the node is not available for the user
+ * (e.g. unshared with the user).
+ */
+export type MaybeMissingNode = Result<NodeEntity, DegradedNode | MissingNode>;
+export type MissingNode = {
+    missingUid: string;
+};
+/**
+ * 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
+ * entity is called.
+ */
+export type NodeEntity = {
+    uid: string;
+    parentUid?: string;
+    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
+     * option to decrypt latest versions.
+     */
+    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.
+     */
+    nameAuthor: Author;
+    directMemberRole: MemberRole;
+    type: NodeType;
+    mediaType?: string;
+    /**
+     * Whether the node is shared. If true, the node is shared with at least
+     * one user, or via public link.
+     */
+    isShared: boolean;
+    /**
+     * Created on server date.
+     */
+    creationTime: Date;
+    trashTime?: Date;
+    /**
+     * Total size of all revisions, encrypted size on the server.
+     */
+    totalStorageSize?: number;
+    activeRevision?: Revision;
+    folder?: {
+        claimedModificationTime?: Date;
+    };
+};
+/**
+ * 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.
+ */
+export type DegradedNode = Omit<NodeEntity, 'name' | 'activeRevision'> & {
+    name: Result<string, Error | InvalidNameError>;
+    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.
+     */
+    errors?: unknown[];
+};
+/**
+ * Invalid name error represents node name that includes invalid characters.
+ */
+export type InvalidNameError = {
+    /**
+     * Placeholder instead of node name that client can use to display.
+     */
+    name: string;
+    error: string;
+};
+export declare enum NodeType {
+    File = "file",
+    Folder = "folder"
+}
+export declare enum MemberRole {
+    Viewer = "viewer",
+    Editor = "editor",
+    Admin = "admin",
+    Inherited = "inherited"
+}
+export type Revision = {
+    uid: string;
+    state: RevisionState;
+    creationTime: Date;
+    contentAuthor: Author;
+    /**
+     * Encrypted size of the revision, as stored on the server.
+     */
+    storageSize: number;
+    /**
+     * Raw size of the revision, as stored in extended attributes.
+     */
+    claimedSize?: number;
+    claimedModificationTime?: Date;
+    claimedDigests?: {
+        sha1?: string;
+    };
+    claimedAdditionalMetadata?: object;
+};
+export declare enum RevisionState {
+    Active = "active",
+    Superseded = "superseded"
+}
+export type NodeOrUid = MaybeNode | NodeEntity | DegradedNode | string;
+export type RevisionOrUid = Revision | string;
+export type NodeResult = {
+    uid: string;
+    ok: true;
+} | {
+    uid: string;
+    ok: false;
+    error: string;
+};

package/dist/interface/nodes.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RevisionState = exports.MemberRole = exports.NodeType = void 0;
+var NodeType;
+(function (NodeType) {
+    NodeType["File"] = "file";
+    NodeType["Folder"] = "folder";
+})(NodeType || (exports.NodeType = NodeType = {}));
+var MemberRole;
+(function (MemberRole) {
+    MemberRole["Viewer"] = "viewer";
+    MemberRole["Editor"] = "editor";
+    MemberRole["Admin"] = "admin";
+    MemberRole["Inherited"] = "inherited";
+})(MemberRole || (exports.MemberRole = MemberRole = {}));
+var RevisionState;
+(function (RevisionState) {
+    RevisionState["Active"] = "active";
+    RevisionState["Superseded"] = "superseded";
+})(RevisionState || (exports.RevisionState = RevisionState = {}));
+//# sourceMappingURL=nodes.js.map

package/dist/interface/nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../../src/interface/nodes.ts"],"names":[],"mappings":";;;AA6HA,IAAY,QAGX;AAHD,WAAY,QAAQ;IAChB,yBAAa,CAAA;IACb,6BAAiB,CAAA;AACrB,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED,IAAY,UAKX;AALD,WAAY,UAAU;IAClB,+BAAiB,CAAA;IACjB,+BAAiB,CAAA;IACjB,6BAAe,CAAA;IACf,qCAAuB,CAAA;AAC3B,CAAC,EALW,UAAU,0BAAV,UAAU,QAKrB;AAsBD,IAAY,aAGX;AAHD,WAAY,aAAa;IACrB,kCAAiB,CAAA;IACjB,0CAAyB,CAAA;AAC7B,CAAC,EAHW,aAAa,6BAAb,aAAa,QAGxB"}

package/dist/interface/result.d.ts

@@ -0,0 +1,9 @@
+export type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare function resultOk<T, E>(value: T): Result<T, E>;
+export declare function resultError<T, E>(error: E): Result<T, E>;

package/dist/interface/result.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resultOk = resultOk;
+exports.resultError = resultError;
+function resultOk(value) {
+    return { ok: true, value };
+}
+function resultError(error) {
+    return { ok: false, error };
+}
+//# sourceMappingURL=result.js.map

package/dist/interface/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/interface/result.ts"],"names":[],"mappings":";;AAIA,4BAEC;AAED,kCAEC;AAND,SAAgB,QAAQ,CAAO,KAAQ;IACnC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC;AAED,SAAgB,WAAW,CAAO,KAAQ;IACtC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC"}

package/dist/interface/sharing.d.ts

@@ -0,0 +1,73 @@
+import { Result } from './result';
+import { UnverifiedAuthorError } from './author';
+import { NodeType, MemberRole, InvalidNameError } from './nodes';
+export type Member = {
+    uid: string;
+    invitationTime: Date;
+    addedByEmail: Result<string, UnverifiedAuthorError>;
+    inviteeEmail: string;
+    role: MemberRole;
+};
+export type ProtonInvitation = Member;
+export type ProtonInvitationWithNode = ProtonInvitation & {
+    node: {
+        name: Result<string, Error | InvalidNameError>;
+        type: NodeType;
+        mediaType?: string;
+    };
+};
+export type NonProtonInvitation = ProtonInvitation & {
+    state: NonProtonInvitationState;
+};
+export declare enum NonProtonInvitationState {
+    Pending = "pending",
+    UserRegistered = "userRegistered"
+}
+export type PublicLink = {
+    uid: string;
+    creationTime: Date;
+    role: MemberRole;
+    url: string;
+    customPassword?: string;
+    expirationTime?: Date;
+};
+export type Bookmark = {
+    uid: string;
+    bookmarkTime: Date;
+    node: {
+        name: Result<string, Error | InvalidNameError>;
+        type: NodeType;
+        mediaType?: string;
+    };
+};
+export type ProtonInvitationOrUid = ProtonInvitation | string;
+export type NonProtonInvitationOrUid = NonProtonInvitation | string;
+export type BookmarkOrUid = Bookmark | string;
+export type ShareNodeSettings = {
+    users?: ShareMembersSettings;
+    publicLink?: SharePublicLinkSettings;
+    emailOptions?: {
+        message?: string;
+        includeNodeName?: boolean;
+    };
+};
+export type ShareMembersSettings = string[] | {
+    email: string;
+    role: MemberRole;
+}[];
+export type SharePublicLinkSettings = boolean | SharePublicLinkSettingsObject;
+export type SharePublicLinkSettingsObject = {
+    role: MemberRole;
+    customPassword?: string | undefined;
+    expiration?: Date | undefined;
+};
+export type ShareResult = {
+    protonInvitations: ProtonInvitation[];
+    nonProtonInvitations: NonProtonInvitation[];
+    members: Member[];
+    publicLink?: PublicLink;
+};
+export type UnshareNodeSettings = {
+    users?: string[];
+    publicLink?: 'remove';
+};

package/dist/interface/sharing.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonProtonInvitationState = void 0;
+var NonProtonInvitationState;
+(function (NonProtonInvitationState) {
+    NonProtonInvitationState["Pending"] = "pending";
+    NonProtonInvitationState["UserRegistered"] = "userRegistered";
+})(NonProtonInvitationState || (exports.NonProtonInvitationState = NonProtonInvitationState = {}));
+//# sourceMappingURL=sharing.js.map

package/dist/interface/sharing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing.js","sourceRoot":"","sources":["../../src/interface/sharing.ts"],"names":[],"mappings":";;;AA0BA,IAAY,wBAGX;AAHD,WAAY,wBAAwB;IAChC,+CAAmB,CAAA;IACnB,6DAAiC,CAAA;AACrC,CAAC,EAHW,wBAAwB,wCAAxB,wBAAwB,QAGnC"}

package/dist/interface/telemetry.d.ts

@@ -0,0 +1,61 @@
+export interface Telemetry<MetricEvent> {
+    getLogger: (name: string) => Logger;
+    logEvent: (event: MetricEvent) => void;
+}
+export interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string, error?: unknown): void;
+}
+export type MetricEvent = MetricAPIRetrySucceededEvent | MetricUploadEvent | MetricDownloadEvent | MetricDecryptionErrorEvent | MetricVerificationErrorEvent | MetricBlockVerificationErrorEvent | MetricVolumeEventsSubscriptionsChangedEvent;
+export interface MetricAPIRetrySucceededEvent {
+    eventName: 'apiRetrySucceeded';
+    url: string;
+    failedAttempts: number;
+}
+export interface MetricUploadEvent {
+    eventName: 'upload';
+    context?: MetricContext;
+    uploadedSize: number;
+    expectedSize: number;
+    error?: MetricsUploadErrorType;
+}
+export type MetricsUploadErrorType = 'server_error' | 'network_error' | 'integrity_error' | 'rate_limited' | '4xx' | '5xx' | 'unknown';
+export interface MetricDownloadEvent {
+    eventName: 'download';
+    context?: MetricContext;
+    downloadedSize: number;
+    claimedFileSize?: number;
+    error?: MetricsDownloadErrorType;
+}
+export type MetricsDownloadErrorType = 'server_error' | 'network_error' | 'decryption_error' | 'integrity_error' | 'rate_limited' | '4xx' | '5xx' | 'unknown';
+export interface MetricDecryptionErrorEvent {
+    eventName: 'decryptionError';
+    context?: MetricContext;
+    field: MetricsDecryptionErrorField;
+    fromBefore2024?: boolean;
+    error?: unknown;
+}
+export type MetricsDecryptionErrorField = 'shareKey' | 'nodeKey' | 'nodeName' | 'nodeHashKey' | 'nodeExtendedAttributes' | 'nodeContentKey' | 'content';
+export interface MetricVerificationErrorEvent {
+    eventName: 'verificationError';
+    context?: MetricContext;
+    field: MetricVerificationErrorField;
+    addressMatchingDefaultShare?: boolean;
+    fromBefore2024?: boolean;
+}
+export type MetricVerificationErrorField = 'shareKey' | 'nodeKey' | 'nodeName' | 'nodeHashKey' | 'nodeExtendedAttributes' | 'nodeContentKey' | 'content';
+export interface MetricBlockVerificationErrorEvent {
+    eventName: 'blockVerificationError';
+    retryHelped: boolean;
+}
+export interface MetricVolumeEventsSubscriptionsChangedEvent {
+    eventName: 'volumeEventsSubscriptionsChanged';
+    numberOfVolumeSubscriptions: number;
+}
+export declare enum MetricContext {
+    OwnVolume = "own_volume",
+    Shared = "shared",
+    SharedPublic = "shared_public"
+}

package/dist/interface/telemetry.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricContext = void 0;
+;
+;
+;
+;
+;
+;
+;
+var MetricContext;
+(function (MetricContext) {
+    MetricContext["OwnVolume"] = "own_volume";
+    MetricContext["Shared"] = "shared";
+    MetricContext["SharedPublic"] = "shared_public";
+})(MetricContext || (exports.MetricContext = MetricContext = {}));
+;
+//# sourceMappingURL=telemetry.js.map

package/dist/interface/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/interface/telemetry.ts"],"names":[],"mappings":";;;AAyBC,CAAC;AAQD,CAAC;AAgBD,CAAC;AAiBD,CAAC;AAgBD,CAAC;AAaD,CAAC;AAKD,CAAC;AAEF,IAAY,aAIX;AAJD,WAAY,aAAa;IACrB,yCAAwB,CAAA;IACxB,kCAAiB,CAAA;IACjB,+CAA8B,CAAA;AAClC,CAAC,EAJW,aAAa,6BAAb,aAAa,QAIxB;AAAA,CAAC"}

package/dist/interface/thumbnail.d.ts

@@ -0,0 +1,17 @@
+export type Thumbnail = {
+    type: ThumbnailType;
+    thumbnail: Uint8Array;
+};
+export declare enum ThumbnailType {
+    Type1 = 1,
+    Type2 = 2
+}
+export type ThumbnailResult = {
+    nodeUid: string;
+    ok: true;
+    thumbnail: Uint8Array;
+} | {
+    nodeUid: string;
+    ok: false;
+    error: string;
+};

package/dist/interface/thumbnail.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThumbnailType = void 0;
+var ThumbnailType;
+(function (ThumbnailType) {
+    ThumbnailType[ThumbnailType["Type1"] = 1] = "Type1";
+    ThumbnailType[ThumbnailType["Type2"] = 2] = "Type2";
+})(ThumbnailType || (exports.ThumbnailType = ThumbnailType = {}));
+//# sourceMappingURL=thumbnail.js.map

package/dist/interface/thumbnail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail.js","sourceRoot":"","sources":["../../src/interface/thumbnail.ts"],"names":[],"mappings":";;;AAMA,IAAY,aAGX;AAHD,WAAY,aAAa;IACrB,mDAAS,CAAA;IACT,mDAAS,CAAA;AACb,CAAC,EAHW,aAAa,6BAAb,aAAa,QAGxB"}

package/dist/interface/upload.d.ts

@@ -0,0 +1,16 @@
+import { Thumbnail } from "./thumbnail";
+export type UploadMetadata = {
+    mediaType: string;
+    expectedSize: number;
+    modificationTime?: Date;
+    additionalMetadata?: object;
+};
+export interface Fileuploader {
+    writeStream(stream: ReadableStream, thumnbails: Thumbnail[], onProgress?: (uploadedBytes: number) => void): UploadController;
+    writeFile(fileObject: File, thumnbails: Thumbnail[], onProgress?: (uploadedBytes: number) => void): UploadController;
+}
+export interface UploadController {
+    pause(): void;
+    resume(): void;
+    completion(): Promise<string>;
+}

package/dist/interface/upload.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=upload.js.map

package/dist/interface/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../src/interface/upload.ts"],"names":[],"mappings":""}

package/dist/internal/apiService/apiService.d.ts

@@ -0,0 +1,51 @@
+import { ProtonDriveHTTPClient, ProtonDriveTelemetry } from "../../interface";
+import { SDKEvents } from '../sdkEvents';
+/**
+ * Provides API communication used withing the Drive SDK.
+ *
+ * The service is responsible for handling general headers, errors, conversion,
+ * rate limiting, or basic re-tries.
+ *
+ * Error handling includes:
+ *
+ * * exception from HTTP client
+ *   * retry on offline exc. (with delay from OFFLINE_RETRY_DELAY_SECONDS)
+ *   * retry on timeout exc. (with delay from SERVER_ERROR_RETRY_DELAY_SECONDS)
+ *   * retry ONCE on any exc. (with delay from GENERAL_RETRY_DELAY_SECONDS)
+ * * HTTP status 429
+ *   * retry (with delay from `retry-after` header or DEFAULT_429_RETRY_DELAY_SECONDS)
+ *   * if too many subsequent 429s, stop further requests (defined in TOO_MANY_SUBSEQUENT_429_ERRORS)
+ *   * when limit is reached, cool down for TOO_MANY_SUBSEQUENT_429_ERRORS_TIMEOUT_IN_SECONDS
+ * * HTTP status 5xx
+ *   * retry ONCE (with delay from SERVER_ERROR_RETRY_DELAY_SECONDS)
+ *   * if too many subsequent 5xxs, stop further requests (defined in TOO_MANY_SUBSEQUENT_SERVER_ERRORS)
+ *   * when limit is reached, cool down for TOO_MANY_SUBSEQUENT_SERVER_ERRORS_TIMEOUT_IN_SECONDS
+ */
+export declare class DriveAPIService {
+    private telemetry;
+    private sdkEvents;
+    private httpClient;
+    private baseUrl;
+    private language;
+    private subsequentTooManyRequestsCounter;
+    private lastTooManyRequestsErrorAt?;
+    private subsequentServerErrorsCounter;
+    private lastServerErrorAt?;
+    private logger;
+    constructor(telemetry: ProtonDriveTelemetry, sdkEvents: SDKEvents, httpClient: ProtonDriveHTTPClient, baseUrl: string, language: string);
+    get<ResponsePayload>(url: string, signal?: AbortSignal): Promise<ResponsePayload>;
+    post<RequestPayload, ResponsePayload>(url: string, data?: RequestPayload, signal?: AbortSignal): Promise<ResponsePayload>;
+    put<RequestPayload, ResponsePayload>(url: string, data: RequestPayload, signal?: AbortSignal): Promise<ResponsePayload>;
+    delete<Response>(url: string, signal?: AbortSignal): Promise<Response>;
+    private makeRequest;
+    getBlockStream(baseUrl: string, token: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    postBlockStream(baseUrl: string, token: string, data: XMLHttpRequestBodyInit, onProgress?: (uploadedBytes: number) => void, signal?: AbortSignal): Promise<void>;
+    private makeStorageRequest;
+    private fetch;
+    private get hasReachedTooManyRequestsErrorLimit();
+    private tooManyRequestsErrorHappened;
+    private clearSubsequentTooManyRequestsError;
+    private get hasReachedServerErrorLimit();
+    private serverErrorHappened;
+    private clearSubsequentServerErrors;
+}