DOCSEARCHbyAlgolia
Submit Docs

Proton Drive SDK

repository·main·Indexed 20 days ago

https://github.com/protondriveapps/sdk

A high-level interface for interacting with Proton Drive, handling encryption and metadata processing. It includes a TypeScript SDK (@protontech/drive-sdk), a C# SDK, and incubating bindings for Kotlin and Swift. The repository also provides the proton-drive-cli (v0.0.1) for automation, scripting, and filesystem management, featuring browser-based authentication and structured JSON output.

Tokens
38.1K
Snippets
120
Records
167
Agent score
70%

What's inside protondriveapps-sdk

  1. Overview of the Proton Drive SDK modules

    main

    The Proton Drive SDK provides a high-level interface for interacting with Proton Drive. It is currently organized into the following modules:

    • Client: The core integration module. It handles folder listing, file uploads/downloads, moving, renaming, trashing, and other file operations. It also supports event-based update polling and sharing.
    • Sync (Coming soon): High-level synchronization functionality built on top of the Client module.
    • Search (Coming soon): High-level search functionality built on top of the Client module.

  2. Available SDK languages and packages

    main

    The Proton Drive SDK provides high-level interfaces for interacting with Proton Drive across multiple platforms.

    • TypeScript: Native SDK available on npm as @protontech/drive-sdk.
    • C#: Native SDK located in the client/cs/ directory.
    • Kotlin: Bindings that wrap the C# SDK (currently in incubation).
    • Swift: Bindings that wrap the C# SDK (currently in incubation), available on GitHub as sdk-swift.

    Note: Kotlin and Swift bindings are in the incubation phase and their interfaces are not guaranteed to be stable across releases.

  3. Use the Account implementation for the Drive SDK

    main

    The account module provides account login, session management, and account API access. It is designed to be used in combination with the Proton Drive SDK to provide account-related functionality to a client.

    Note: This module is currently in an incubating state. It is not intended for public distribution or promotion outside of the incubating directory and is provided as a temporary solution until the official Account SDK is released. It may lack certain features required for full production use.

  4. SDK Scope and Limitations

    main

    The SDK focuses exclusively on Proton Drive business logic. It does not provide the following:

    • Authentication or login flows
    • Session management
    • User address provider

    Official Proton Drive clients implement these pieces by wiring them into the SDK. Users should treat official clients as the reference for how to handle authentication and session management until standalone integration support is documented.

  5. Understand where Proton Drive CLI data is stored

    main

    The CLI stores data in different locations depending on the OS and whether PROTON_DRIVE_CACHE_DIR is set. If PROTON_DRIVE_CACHE_DIR is provided, all data is consolidated there.

    Default Locations

    PurposemacOSWindowsLinux / Unix
    Cache~/Library/Caches/proton-drive-cli%LOCALAPPDATA%\proton-drive-cli\Cache$XDG_CACHE_HOME/proton-drive-cli or ~/.cache/proton-drive-cli
    App data~/Library/Application Support/proton-drive-cli%LOCALAPPDATA%\proton-drive-cli\Data$XDG_DATA_HOME/proton-drive-cli or ~/.local/share/proton-drive-cli
    Logs~/Library/Logs/proton-drive-cli%LOCALAPPDATA%\proton-drive-cli\Logs$XDG_STATE_HOME/proton-drive-cli or ~/.local/state/proton-drive-cli

    Credentials Storage

    Controlled by PROTON_DRIVE_CREDENTIALS_STORE:

    • keychain (default): Stored in the OS secret store under service ch.proton.drive/drive-sdk-cli.
    • pass: Stored as a GPG-encrypted entry ch.proton.drive/drive-sdk-cli/auth-session in pass.
    • unsafe_file: Stored as plaintext auth-session.json in the app data folder (use for testing only).

  6. Upcoming cryptographic model change

    main

    Proton Drive is migrating to a new cryptographic model to improve performance and security, targeted for late 2026 or early 2027.

    Critical Impact:

    • Any client using the old cryptographic model (including older SDK releases) will not be able to interoperate with the service once the migration is complete.
    • You must upgrade to an SDK release that implements the new model to maintain access.
    • Monitor this repository and the changelogs for definitive dates and migration steps.

  7. Target audience and usage suitability

    main

    The SDK's suitability depends on your project type:

    • Proton first-party clients: The primary target. The codebase is validated alongside official Proton Drive apps.
    • Personal, non-commercial projects: Allowed, but users should expect interface changes and an upcoming cryptographic migration. Using the SDK is recommended over raw API calls to ensure correctness, safety, and alignment with rate-limiting behavior.
    • Commercial or production third-party apps: The SDK is not yet ready for third-party production use.

  8. Understand the Incubating Drive SDK modules

    main

    The incubating/ directory contains higher-level Drive SDK modules that extend the core Client module. These modules provide advanced functionality (such as sync or search) used by Proton's first-party clients.

    Important Usage Notes:

    • Stability: Modules in this directory are not yet on the stable release cycle. The public API, documentation, and tests may be incomplete or subject to change without notice.
    • Promotion: Once a module matures, it is moved to the root directory and becomes part of the officially supported SDK.
    • Core vs. Incubating: The core SDK (found in the root) provides fundamental Drive capabilities like folder listing, file upload/download, move, rename, trash, sharing, and event-based polling. Anything building on top of these core capabilities is considered an incubating module.

  9. Generate and upload additional metadata for photo files

    main

    When uploading photos specifically to a photo section, use generateAdditionalPhotoNodeMetadata. This function provides extra fields specifically useful for photo organization, such as captureTime and tags, in addition to the standard additionalMetadata object.

    Pass additionalMetadata, captureTime, and tags into the getFileUploader options to ensure the photo is correctly indexed with its temporal and descriptive data.

    import { generateAdditionalPhotoNodeMetadata } from '@protontech/drive-sdk/additionalNodeMetadata';

const { additionalMetadata, captureTime, tags } = await generateAdditionalPhotoNodeMetadata(file, mediaType, mediaInfo);

const uploader = sdk.getFileUploader(file.name, {
    mediaType: file.type,
    expectedSize: file.size,
    expectedSha1,
    additionalMetadata,
    captureTime,
    tags,
});
const controller = uploader.uploadFromFile(file, thumbnails);
await controller.completion();

  10. Initialize the ProtonDriveClient

    main

    To use the SDK, start by creating an instance of the ProtonDriveClient. This instance serves as the primary entry point for interacting with the service. Once instantiated, you can use its methods to:

    • Access nodes
    • Manage devices
    • Upload and download content
    • Manage sharing permissions

    Note: Only use the public API exported by the library. Internal implementation details are subject to change without warning.

  11. Generate SDK code reference

    main

    While full documentation is being prepared, you can generate the code reference for the C# or TypeScript SDKs using the following commands:

    For C#:

    cd client/cs && dotnet docfx metadata docfx/docfx.json && dotnet docfx build docfx/docfx.json

    For TypeScript/JS:

    cd client/js && npm run generate-docs
    cd client/cs && dotnet docfx metadata docfx/docfx.json && dotnet docfx build docfx/docfx.json
cd client/js && npm run generate-docs

  12. Generate and upload additional node metadata for regular files

    main

    Use the generateAdditionalNodeMetadata function to extract EXIF and other attributes (like GPS location, camera info, and media dimensions) from a file. This creates a unified metadata object that can be passed to the getFileUploader to enable faster searching and filtering of the file later.

    To use this, call generateAdditionalNodeMetadata(file, mediaType, mediaInfo), then include the resulting additionalMetadata in the options object passed to sdk.getFileUploader.

    import { generateAdditionalNodeMetadata } from '@protontech/drive-sdk/additionalNodeMetadata';

const { additionalMetadata } = await generateAdditionalNodeMetadata(file, mediaType, mediaInfo);

const uploader = sdk.getFileUploader(parentNodeUid, file.name, {
    mediaType: file.type,
    expectedSize: file.size,
    expectedSha1,
    additionalMetadata,
});
const controller = uploader.uploadFromFile(file, thumbnails);
await controller.completion();