{"id":10890,"library":"files.com","title":"Files.com JavaScript SDK","description":"The Files.com JavaScript SDK, currently at version 1.2.610, provides a direct, high-performance integration with the Files.com cloud-native MFT, SFTP, and secure file-sharing platform. It enables applications to programmatically interact with files, folders, users, automations, and other administrative tasks through Files.com's RESTful APIs over HTTPS. This SDK is a core internal component for Files.com, ensuring it is actively maintained, continuously updated, and performant. Releases are frequent, following a MAJOR.MINOR.BUILDNUMBER semantic versioning, where MAJOR or MINOR changes may introduce breaking changes, and BUILDNUMBER updates are generally non-disruptive. Key differentiators include unifying SFTP, AS2, and HTTPS protocols, offering 50+ native connectors, military-grade encryption, and a unified platform for governance, visibility, and compliance, aiming to replace brittle legacy file transfer solutions with a robust, always-on fabric for automating mission-critical file flows.","status":"active","version":"1.2.610","language":"javascript","source_language":"en","source_url":"https://github.com/Files-com/files-sdk-javascript","tags":["javascript","files.com","cloud storage","api"],"install":[{"cmd":"npm install files.com","lang":"bash","label":"npm"},{"cmd":"yarn add files.com","lang":"bash","label":"yarn"},{"cmd":"pnpm add files.com","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For CommonJS `require()`, remember to append `.default` to access the main export. The import path includes `/lib/` for direct module access.","wrong":"const Files = require('files.com/lib/Files.js')","symbol":"Files","correct":"import Files from 'files.com/lib/Files.js';"},{"note":"This pattern applies to all model imports from `files.com/lib/models/`. CommonJS `require()` users must append `.default`.","wrong":"const User = require('files.com/lib/models/User.js')","symbol":"User","correct":"import User from 'files.com/lib/models/User.js';"},{"note":"Error classes and other utilities are often named exports. For CommonJS `require()`, access named exports via `.default` like `const { FilesApiError } = require('files.com/lib/Errors').default;`.","wrong":"const FilesApiError = require('files.com/lib/Errors')","symbol":"FilesApiError","correct":"import { FilesApiError } from 'files.com/lib/Errors';"}],"quickstart":{"code":"import Files from 'files.com/lib/Files.js';\nimport User from 'files.com/lib/models/User.js';\nimport * as FilesErrors from 'files.com/lib/Errors';\n\nconst API_KEY = process.env.FILESCOM_API_KEY ?? '';\n\nif (!API_KEY) {\n  console.error('FILESCOM_API_KEY environment variable is not set.');\n  process.exit(1);\n}\n\nFiles.setApiKey(API_KEY);\n\nasync function fetchCurrentUser() {\n  try {\n    // Retrieve the current authenticated user's details\n    const user = await User.current();\n    console.log(`Successfully authenticated as user: ${user.name} (ID: ${user.id})`);\n    console.log('User details:', user.attributes);\n  } catch (error) {\n    if (error instanceof FilesErrors.FilesApiError) {\n      console.error(`Files.com API Error: ${error.message} (Status: ${error.httpStatus})`);\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n    process.exit(1);\n  }\n}\n\nfetchCurrentUser();","lang":"javascript","description":"Initializes the Files.com SDK with an API key from environment variables and fetches the current authenticated user's details, demonstrating basic authentication and error handling."},"warnings":[{"fix":"Change `const MyModule = require('files.com/lib/module')` to `const MyModule = require('files.com/lib/module').default`.","message":"When using CommonJS `require()` syntax for SDK modules, you must append `.default` to access the main export (e.g., `require('files.com/lib/Files.js').default`). Omitting this will result in runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the API key used has appropriate permissions for the intended operations. Generate administrator API keys for site-wide administrative tasks, or use specific user keys for limited scope operations. For enhanced security, prefer non-administrator user keys whenever possible.","message":"API keys have different scopes. User-specific API keys only grant access based on that user's permissions. An administrator's API key provides full access, while a non-administrator's key restricts access to only files the user can access, without site administration functions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use the full, explicit import path for SDK modules, such as `import Files from 'files.com/lib/Files.js';`.","message":"The import paths for SDK modules are specific and typically include `/lib/` (e.g., `files.com/lib/Files.js` or `files.com/lib/models/User.js`). Directly importing from `files.com` without `/lib/` will result in module not found errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For granular control, explicitly pass the API key in the options parameter of relevant API calls or model constructors, for example: `new User(params, { apiKey: 'USER_SPECIFIC_KEY' })`.","message":"While `Files.setApiKey()` configures a global API key, it's possible to override this on a per-request or per-object basis by passing `{ apiKey: 'YOUR_KEY' }` in the options parameter of model constructors or API calls. This is important for multi-tenancy or different permission contexts.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If experiencing connection errors, verify that your network allows outbound HTTPS traffic on port 443 to `files.com` endpoints.","message":"The Files.com SDK uses HTTPS (port 443) for all communication. While firewall changes are typically not required, connectivity issues might arise if outgoing HTTPS traffic on port 443 is blocked by network policies.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the release notes and GitHub commit history between major/minor versions to identify breaking changes. Pin your dependency versions to a specific minor version (e.g., `1.2.x`) to prevent automatic disruptive updates.","message":"Files.com SDKs follow semantic versioning (MAJOR.MINOR.BUILDNUMBER). Major or minor version changes may introduce breaking changes, requiring review before upgrading. Build number changes are generally non-disruptive bug fixes or performance improvements.","severity":"breaking","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":"If using CommonJS `require()`, ensure you append `.default`: `const Files = require('files.com/lib/Files.js').default;`. If using ES modules, ensure your build system correctly handles exports.","cause":"Attempting to use a CommonJS `require()` without appending `.default` to access the main export in a mixed ES module environment, or incorrect ES Module interop.","error":"TypeError: files_com_lib_Files_js__WEBPACK_IMPORTED_MODULE_0__.default is not a constructor"},{"fix":"Set the API key globally with `Files.setApiKey('YOUR_API_KEY');` at application startup, or provide it as an option in specific API calls or model constructors: `new User(params, { apiKey: 'YOUR_API_KEY' });`.","cause":"The SDK was initialized or an API call was made without a global API key set via `Files.setApiKey()` or a per-request/per-object API key provided.","error":"Error: No API key provided"},{"fix":"Correct the import path to include `/lib/`, for example: `import Files from 'files.com/lib/Files.js';` or `const Files = require('files.com/lib/Files.js').default;`.","cause":"Incorrect import path for an SDK module. The SDK modules are nested under the `lib/` directory.","error":"Module not found: Error: Can't resolve 'files.com/Files'"},{"fix":"Verify the API key in your Files.com account, ensuring it is active and has the necessary permissions. Regenerate the key if necessary. Check if a user-specific API key has administrative privileges if administrative actions are being performed.","cause":"The provided API key is invalid, revoked, expired, or does not have sufficient permissions for the attempted operation.","error":"FilesApiError: Bad credentials (Status: 401)"}],"ecosystem":"npm"}