Files.com JavaScript SDK

Common errors

• TypeError: files_com_lib_Files_js__WEBPACK_IMPORTED_MODULE_0__.default is not a constructor

  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.
  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.

• Error: No API key provided

  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.
  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' });`.

• Module not found: Error: Can't resolve 'files.com/Files'

  cause Incorrect import path for an SDK module. The SDK modules are nested under the `lib/` directory.
  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;`.

• FilesApiError: Bad credentials (Status: 401)

  cause The provided API key is invalid, revoked, expired, or does not have sufficient permissions for the attempted operation.
  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.

Warnings

• gotcha 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.
  Fix: Change `const MyModule = require('files.com/lib/module')` to `const MyModule = require('files.com/lib/module').default`.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Always use the full, explicit import path for SDK modules, such as `import Files from 'files.com/lib/Files.js';`.
• gotcha 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.
  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' })`.
• gotcha 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.
  Fix: If experiencing connection errors, verify that your network allows outbound HTTPS traffic on port 443 to `files.com` endpoints.
• breaking 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.
  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.

Install

• npm install files.com npm
• yarn add files.com yarn
• pnpm add files.com pnpm

Imports

• Files
  wrong:

  const Files = require('files.com/lib/Files.js')

  correct:

  import Files from 'files.com/lib/Files.js';

  For CommonJS `require()`, remember to append `.default` to access the main export. The import path includes `/lib/` for direct module access.
• User
  wrong:

  const User = require('files.com/lib/models/User.js')

  correct:

  import User from 'files.com/lib/models/User.js';

  This pattern applies to all model imports from `files.com/lib/models/`. CommonJS `require()` users must append `.default`.
• FilesApiError
  wrong:

  const FilesApiError = require('files.com/lib/Errors')

  correct:

  import { FilesApiError } from 'files.com/lib/Errors';

  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;`.

Quickstart

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.

import Files from 'files.com/lib/Files.js';
import User from 'files.com/lib/models/User.js';
import * as FilesErrors from 'files.com/lib/Errors';

const API_KEY = process.env.FILESCOM_API_KEY ?? '';

if (!API_KEY) {
  console.error('FILESCOM_API_KEY environment variable is not set.');
  process.exit(1);
}

Files.setApiKey(API_KEY);

async function fetchCurrentUser() {
  try {
    // Retrieve the current authenticated user's details
    const user = await User.current();
    console.log(`Successfully authenticated as user: ${user.name} (ID: ${user.id})`);
    console.log('User details:', user.attributes);
  } catch (error) {
    if (error instanceof FilesErrors.FilesApiError) {
      console.error(`Files.com API Error: ${error.message} (Status: ${error.httpStatus})`);
    } else {
      console.error('An unexpected error occurred:', error);
    }
    process.exit(1);
  }
}

fetchCurrentUser();