Smartsheet JavaScript SDK

Common errors

• Error: SMARTSHEET_ACCESS_TOKEN environment variable is not set.

  cause The Smartsheet client was initialized without an access token, or the token was invalid.
  fix Provide a valid Smartsheet API access token, ideally through an environment variable like `SMARTSHEET_ACCESS_TOKEN`, or directly in the `createClient` call (not recommended for production).

• TypeError: smartsheet.sheets.getWorkspace is not a function

  cause Attempting to call a deprecated method (`getWorkspace` or `getFolder`) that has been removed or replaced in newer SDK versions.
  fix Update your code to use the new methods introduced in v4.4.0: `getWorkspaceMetadata()` and `getWorkspaceChildren()` for workspaces, and `getFolderMetadata()` and `getFolderChildren()` for folders.

• ERR_MODULE_NOT_FOUND: Cannot find module 'smartsheet'

  cause Incorrect module import path or attempting a CommonJS `require` in an ESM module without proper configuration (or vice versa).
  fix Ensure `npm install smartsheet` has been run. For ESM, use `import { createClient } from 'smartsheet';`. For CommonJS, use `const { createClient } = require('smartsheet');`. Check your `package.json` `type` field if encountering issues in mixed environments.

Warnings

• breaking Older sharing endpoints were deprecated in favor of new ones. Existing code using the deprecated endpoints may eventually break or behave unexpectedly.
  Fix: Migrate your code to use the newly introduced sharing endpoints. Refer to the Smartsheet API documentation for the updated methods.
• breaking The `getWorkspace()` and `getFolder()` methods were deprecated. Developers must now use `getWorkspaceMetadata()` paired with `getWorkspaceChildren()` (and similarly for folders) to retrieve equivalent data.
  Fix: Replace calls to `getWorkspace()` with `smartsheet.workspaces.getWorkspaceMetadata(id)` and `smartsheet.workspaces.getWorkspaceChildren(id)`. Apply similar changes for folder methods.
• gotcha Versions prior to 4.2.3 had a bug where the request body was not correctly resent during retries for POST/PUT methods, potentially leading to data loss or incorrect state on intermittent network failures.
  Fix: Upgrade to version 4.2.3 or later to ensure correct retry behavior for all HTTP methods.
• gotcha The Smartsheet SDK requires Node.js version 14.x or later. Using older, unsupported Node.js versions may lead to unexpected errors, security vulnerabilities, or installation failures.
  Fix: Ensure your Node.js environment is actively supported (v14.x or later). Update Node.js to a compatible version.

Install

• npm install smartsheet npm
• yarn add smartsheet yarn
• pnpm add smartsheet pnpm

Imports

• createClient
  wrong:

  import smartsheet from 'smartsheet'; const client = smartsheet.createClient(...);

  correct:

  import { createClient } from 'smartsheet';

  For modern ESM usage, `createClient` is a named export. The SDK's README still shows a CommonJS `require` pattern for the full module object.
• createClient (CommonJS)
  wrong:

  const smartsheet = require('smartsheet'); const client = smartsheet.createClient(...);

  correct:

  const { createClient } = require('smartsheet');

  While the README uses the older `const client = require('smartsheet'); const smartsheet = client.createClient(...)` pattern, destructuring is generally preferred in CommonJS for clarity.
• SmartsheetClient (Type)
  wrong:

  import { SmartsheetClient } from 'smartsheet';

  correct:

  import type { SmartsheetClient } from 'smartsheet';

  When importing types in TypeScript, it's best practice to use `import type` to ensure they are stripped during compilation.

Quickstart

This quickstart demonstrates how to initialize the Smartsheet client, list all available sheets, and then load the details of the first sheet found using asynchronous `await` syntax.

import { createClient } from 'smartsheet';

const accessToken = process.env.SMARTSHEET_ACCESS_TOKEN ?? ''; // Load from environment variable for security

if (!accessToken) {
  console.error('Error: SMARTSHEET_ACCESS_TOKEN environment variable is not set.');
  process.exit(1);
}

// Initialize the client
const smartsheet = createClient({
  accessToken: accessToken,
  logLevel: 'info' // Can be 'info', 'warn', 'error', 'debug'
});

// Set queryParameters for `include` and pagination
const options = {
  queryParameters: {
    include: 'attachments',
    includeAll: true
  }
};

async function listAndLoadSheets() {
  try {
    // List all sheets
    const result = await smartsheet.sheets.listSheets(options);
    if (result.data && result.data.length > 0) {
      const sheetId = result.data[0].id; // Choose the first sheet

      // Load one sheet
      const sheetInfo = await smartsheet.sheets.getSheet({ sheetId: sheetId });
      console.log('Successfully loaded sheet:', sheetInfo.name, 'with ID:', sheetInfo.id);
      // console.log(JSON.stringify(sheetInfo, null, 2)); // Uncomment to see full sheet data
    } else {
      console.log('No sheets found in your Smartsheet account.');
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

listAndLoadSheets();