client-sf-bulk2

Typed Salesforce Bulk API 2.0 client for Node.js. Run a SOQL query or a CSV ingest job in one line, and follow long-running jobs with an event emitter — without hand-rolling the create / upload / start / poll / paginate dance.

Install

npm install client-sf-bulk2

TypeScript declarations are bundled — no @types/ package needed.

Quick start

Export a full Salesforce object to CSV in one call:

import { BulkAPI, Parameters, QueryInput } from 'client-sf-bulk2';

const parameters: Parameters = {
  accessToken: '<your access token>',
  apiVersion: '55.0',
  instanceUrl: 'https://your-org.my.salesforce.com',
};

const bulkAPI = new BulkAPI(parameters);

const queryInput: QueryInput = {
  operation: 'query',
  query: 'SELECT Id, Name FROM Account',
};

// Submits the job, waits for it to finish, follows every locator page,
// and returns the whole result set as CSV.
const csv = await bulkAPI.submitAndGetQueryResults(queryInput, 10000);

And insert a CSV file in one call:

import { BulkAPI, JobUploadRequest } from 'client-sf-bulk2';

const jobRequest: JobUploadRequest = { object: 'Account', operation: 'insert' };

// Creates the job, uploads the file, starts it, waits for completion.
const jobInfo = await bulkAPI.createAndWaitJobResult(jobRequest, './accounts.csv');
console.log(jobInfo.numberRecordsProcessed, jobInfo.numberRecordsFailed);

Why this library

Salesforce's Bulk API 2.0 is a multi-step protocol: create a job, upload the data, start it, poll until it leaves InProgress, then walk Sforce-Locator pages to collect results. Doing that by hand is where most of the code goes.

• One-line happy paths. submitAndGetQueryResults and createAndWaitJobResult collapse the whole sequence into a single await.
• Pagination handled. getAllQueryResults follows Sforce-Locator until exhausted and stitches the CSV, stripping repeated headers.
• Job monitoring built in. Subscribe to MonitorJob for state on every poll instead of writing your own loop.
• Typed end to end. Every request and response shape is an exported interface; strict TypeScript throughout.
• Small surface. One runtime dependency (axios).

It is not an ORM and it does not do authentication — bring your own token (see below). If you need the full Salesforce API surface, use jsforce; if you need Bulk 2.0 specifically and want it terse, use this.

Authenticating

This library takes an access token; it does not obtain one. Any Salesforce auth flow works. Two common options:

// With jsforce
import jsforce from 'jsforce';

const conn = new jsforce.Connection({});
await conn.login(process.env.SF_USERNAME!, process.env.SF_PASSWORD!);

const bulkAPI = new BulkAPI({
  accessToken: conn.accessToken,
  apiVersion: '55.0',
  instanceUrl: conn.instanceUrl,
});

// With client-sf-oauth (username-password flow)
import { SF_PassConnect } from 'client-sf-oauth';

const connection = new SF_PassConnect({
  clientId: process.env.SF_CLIENT_ID!,
  clientSecret: process.env.SF_CLIENT_SECRET!,
  username: process.env.SF_USERNAME!,
  password: process.env.SF_PASSWORD!,
  usertoken: process.env.SF_USER_TOKEN!,
  host: process.env.SF_HOST!,
});

const result = await connection.requestAccessToken();

const bulkAPI = new BulkAPI({
  accessToken: result.data.access_token,
  apiVersion: '55.0',
  instanceUrl: result.data.instance_url,
});

Set isTooling: true in Parameters to target the Tooling API instead.

Error handling

Errors are not caught for you — axios rejections propagate unchanged, so you wrap calls yourself.

Never log a raw axios error. It carries error.config.headers.Authorization, which is your live Salesforce access token. Log error.message, or redact before logging.

try {
  const csv = await bulkAPI.submitAndGetQueryResults(queryInput);
} catch (error) {
  console.error(error instanceof Error ? error.message : error);
}

Monitoring a long-running job

MonitorJob is a module-level EventEmitter shared by every BulkAPI instance in the process. It emits monitoring on each poll while waitJobEnd or waitQueryEnd is running.

import { BulkAPI, MonitorJob, JobUploadRequest } from 'client-sf-bulk2';

MonitorJob.on('monitoring', (state) => console.log('job state:', state));

const jobRequest: JobUploadRequest = { object: 'Account', operation: 'insert' };
const job = await bulkAPI.createAndStartJob(jobRequest, './accounts.csv');

if (await bulkAPI.waitJobEnd(job.id) === 'JobComplete') {
  const succeeded = await bulkAPI.getJobSuccesfulResults(job.id);
  const failed = await bulkAPI.getJobFailedResults(job.id);
}

API reference

Construct with new BulkAPI(parameters: Parameters).

Query jobs

Method	Returns	Description
submitQueryJob(query)	QueryResponse	Submit a SOQL query job.
getQueryJob(jobId)	QueryResponse	Current state of one query job.
getAllQueryJobInfo(config?)	AllQueryJobsInfoResponse	List query jobs in the org.
abortQueryJob(jobId)	QueryResponse	Abort a running query job.
getQueryResults(jobId, maxRecords?, locator?)	AxiosResponse<string>	One page of CSV results, headers included.
getAllQueryResults(jobId, maxRecords?)	string	Every page, concatenated.
waitQueryEnd(jobId, delay?)	string	Poll until the job reaches a final state. Default delay 3000 ms.
getQueryFinalResults(jobId, maxRecordsByRequest?)	string	Wait, then fetch all results. Default 200 per request.
submitAndGetQueryResults(query, maxRecordsByRequest?)	string	Submit, wait, and fetch all results.

Ingest jobs

Method	Returns	Description
createDataUploadJob(request)	JobUploadResponse	Create an ingest job.
uploadJobData(jobId, filename)	number	Upload a CSV file; resolves to the HTTP status.
startJob(jobId)	JobUploadResponse	Move the job to UploadComplete.
createAndStartJob(request, filename)	JobUploadResponse	Create, upload, and start.
abortJob(jobId)	JobUploadResponse	Abort a running ingest job.
getIngestJobInfo(jobId)	JobInfoResponse	Job state plus processing counters.
waitJobEnd(jobId, delay?)	string	Poll until the job reaches a final state. Default delay 3000 ms.
createAndWaitJobResult(request, filename)	JobInfoResponse	Create, upload, start, and wait.
getJobSuccesfulResults(jobId)	string	CSV of records that succeeded.
getJobFailedResults(jobId)	string	CSV of records that failed.
getJobUnprocessedResults(jobId)	string	CSV of records never processed.

Exported types

Parameters, QueryInput, QueryConfig, QueryResponse, AllQueryJobsInfoResponse, JobUploadRequest, JobUploadResponse, JobInfoResponse, and the MonitorJob emitter.

Key shapes:

interface Parameters {
  accessToken: string;
  apiVersion: string;   // e.g. '55.0'
  instanceUrl: string;
  isTooling?: boolean;
}

interface QueryInput {
  operation: string;    // 'query' | 'queryAll'
  query: string;
  contentType?: string;
  columnDelimiter?: string;
  lineEnding?: string;
}

interface JobUploadRequest {
  object: string;       // e.g. 'Account'
  operation: string;    // 'insert' | 'update' | 'upsert' | 'delete' | 'hardDelete'
  externalIdFieldName?: string;   // required for 'upsert'
  assignmentRuleId?: string;
  columnDelimiter?: string;
  contentType?: string;
  lineEnding?: string;
}

Requirements

• Node.js >= 20.19.0
• A Salesforce access token and instance URL

Reference

• Salesforce Bulk API 2.0 documentation
• Changelog
• Issues

Acknowledgements

Inspired by node-sf-bulk2.

License

MIT