{"id":13090,"library":"dropbox-v2-api","title":"Dropbox V2 API Wrapper for Node.js","description":"This package provides a programmatically generated wrapper for the Dropbox V2 API, specifically designed for Node.js environments. It aims to keep the API surface up-to-date by automatically generating PRs when the official Dropbox endpoint descriptions change. Currently at version 2.5.12, it follows a continuous update model for its API generation, ensuring parity with the Dropbox API. Key differentiators include full support for Node.js streams for efficient file uploads and downloads, direct support for the Dropbox Paper API, and a simple, direct mapping of official Dropbox API resource names. It avoids custom function names, instead relying on a structured object for resource and parameter definitions. The package supports both token-based authentication and the full OAuth2 flow, including refresh token management for offline access. It is primarily consumed as a CommonJS module.","status":"active","version":"2.5.12","language":"javascript","source_language":"en","source_url":"https://github.com/adasq/dropbox-v2-api","tags":["javascript","dropbox","api","v2","wrapper","node"],"install":[{"cmd":"npm install dropbox-v2-api","lang":"bash","label":"npm"},{"cmd":"yarn add dropbox-v2-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add dropbox-v2-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses CommonJS `require()` syntax. Direct ESM `import` is not officially supported without a transpilation step or specific `type: module` configuration in consuming applications. The main export is an object containing the `authenticate` method.","wrong":"import dropboxV2Api from 'dropbox-v2-api';","symbol":"dropboxV2Api","correct":"const dropboxV2Api = require('dropbox-v2-api');"},{"note":"The `authenticate` method is accessed via the `dropboxV2Api` object. It returns a function (`dropbox`) that is then used to make API calls. Do not try to destructure `authenticate` directly from the `require` call unless you are certain of the module's export structure.","wrong":"const dropbox = require('dropbox-v2-api').authenticate(...);","symbol":"authenticate","correct":"const dropbox = dropboxV2Api.authenticate({ token: 'YOUR_TOKEN' });"},{"note":"After authentication, the returned `dropbox` function is the primary interface for all API calls. It takes a single configuration object with `resource` (string) and `parameters` (object) fields, following the official Dropbox API endpoint naming conventions.","wrong":"dropboxV2Api.users.getCurrentAccount({}, callback);","symbol":"API Call Function","correct":"dropbox({ resource: 'users/get_current_account', parameters: {} }, callback);"}],"quickstart":{"code":"const dropboxV2Api = require('dropbox-v2-api');\nconst fs = require('fs');\n\n// Replace with your actual Dropbox access token and desired path\nconst DROPBOX_ACCESS_TOKEN = process.env.DROPBOX_TOKEN ?? 'YOUR_DROPBOX_TOKEN';\nconst DROPBOX_UPLOAD_PATH = '/my-uploaded-file.txt';\nconst LOCAL_FILE_PATH = 'local-file.txt';\n\n// Create a dummy local file for upload example\nfs.writeFileSync(LOCAL_FILE_PATH, 'Hello from dropbox-v2-api!\\nThis is a test upload.');\n\nconst dropbox = dropboxV2Api.authenticate({\n    token: DROPBOX_ACCESS_TOKEN\n});\n\nconsole.log('Listing current account details...');\ndropbox({\n    resource: 'users/get_current_account',\n    parameters: {}\n}, (err, result, response) => {\n    if (err) { \n        console.error('Error getting account details:', err);\n        return;\n    }\n    console.log('Account Details:', result);\n\n    console.log(`Attempting to upload '${LOCAL_FILE_PATH}' to '${DROPBOX_UPLOAD_PATH}'...`);\n    dropbox({\n        resource: 'files/upload',\n        parameters: {\n            path: DROPBOX_UPLOAD_PATH,\n            mode: 'overwrite'\n        },\n        readStream: fs.createReadStream(LOCAL_FILE_PATH)\n    }, (uploadErr, uploadResult, uploadResponse) => {\n        if (uploadErr) {\n            console.error('Error uploading file:', uploadErr);\n            return;\n        }\n        console.log('File uploaded successfully:', uploadResult);\n\n        // Clean up the local dummy file\n        fs.unlinkSync(LOCAL_FILE_PATH);\n        console.log(`Cleaned up local file: ${LOCAL_FILE_PATH}`);\n    });\n});","lang":"javascript","description":"This example demonstrates authenticating with a Dropbox token, fetching current account details, and uploading a local file to Dropbox using Node.js streams. It highlights the basic API call structure."},"warnings":[{"fix":"Refer to the official Dropbox API documentation or the library's `api.json` for the most accurate resource names and parameters, especially after any library updates.","message":"The API resource names and parameter structures are dynamically generated from the official Dropbox API specification. While this ensures currency, minor updates to the underlying Dropbox API could subtly change expected `resource` string values or `parameters` object fields without a major version bump in `dropbox-v2-api`, requiring code adjustments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all API calls and concepts align with Dropbox API v2 documentation. Migrate any legacy v1 codebases to v2 before using this library.","message":"Older versions of the Dropbox API (v1) are not supported. This library is strictly for Dropbox API v2. Attempting to use v1 concepts or endpoints will result in errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Verify that your access token is current and has the necessary scopes. Implement refresh token logic for long-lived access if using OAuth2, by calling `dropbox.refreshToken()` with the stored `refresh_token`.","message":"Incorrect or expired access tokens will result in `AuthError` responses from the Dropbox API, typically indicating a 401 Unauthorized status. Refresh tokens are only available for `token_access_type: 'offline'` during the OAuth2 flow.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always provide a `fs.createReadStream()` or similar readable stream for upload resources. For downloads, ensure you pipe the returned stream to a writable destination, e.g., `fs.createWriteStream()`.","message":"For upload and download operations, this library heavily leverages Node.js streams. Mismanaging stream piping or not providing a `readStream` for upload-type resources (e.g., `files/upload`) will lead to errors or hung connections.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Set `NODE_TLS_REJECT_UNAUTHORIZED='0'` (NOT recommended for production) or configure Node.js to trust the custom CA certificate by setting the `NODE_EXTRA_CA_CERTS` environment variable.","cause":"Often occurs in corporate network environments with SSL inspection or proxy servers that use self-signed certificates, which Node.js's default CA store does not trust.","error":"Error: request to https://api.dropboxapi.com/2/users/get_current_account failed, reason: self signed certificate in certificate chain"},{"fix":"Obtain a new access token, verify its validity, and ensure it has all the required Dropbox API scopes (e.g., `files.content.read`, `files.content.write`, `account_info.read`) for the endpoints you are calling.","cause":"The provided access token is either invalid, expired, or does not have the necessary permissions (scopes) for the requested operation.","error":"Error: { error_summary: 'invalid_access_token/...' }"},{"fix":"Double-check the `path` parameter in your API call. Ensure the path exists and is correctly formatted according to Dropbox's path rules. Verify that the application has permissions to access that specific path.","cause":"The specified file path is invalid, refers to a non-existent file/folder, or violates Dropbox's path restrictions (e.g., invalid characters, exceeding length limits).","error":"Error: { error_summary: 'path/restricted_content/...' }"},{"fix":"Ensure you first call `const dropbox = dropboxV2Api.authenticate({ token: '...' });` and then use the `dropbox` constant as the function to make API requests.","cause":"You are likely attempting to call `dropboxV2Api` directly instead of the function returned by `dropboxV2Api.authenticate()`.","error":"TypeError: dropbox is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}