@salesforce-operations/core

Core SDK for Salesforce operations providing business logic layer between MCP tools and JSForce.

Purpose

This SDK extracts all complex business logic from MCP tool files, allowing:

• 90% reduction in token usage for LLMs (tools become 50-100 lines instead of 1000+)
• Better separation of concerns
• Reusable across different contexts (not just MCP)
• Easier to test and maintain

Architecture

MCP Tools (50-100 lines) → SDK (this package) → JSForce → Salesforce API

Installation

npm install @salesforce-operations/core jsforce

Usage

Query Operations

import { SalesforceSDK } from '@salesforce-operations/core';
import jsforce from 'jsforce';

const conn = new jsforce.Connection({
  instanceUrl: process.env.SALESFORCE_INSTANCE_URL,
  accessToken: process.env.SALESFORCE_ACCESS_TOKEN
});

// Execute a query
const result = await SalesforceSDK.query(conn, {
  objectName: 'Account',
  fields: ['Id', 'Name', 'Industry'],
  whereClause: 'Industry = ?',
  parameters: ['Technology'],
  limit: 10
});

console.log(`Found ${result.totalSize} records in ${result.executionTime}ms`);

Query Builder (Fluent API)

const result = await SalesforceSDK.createQuery('Account')
  .select('Id', 'Name', 'Industry')
  .where('Industry = ?', 'Technology')
  .and('AnnualRevenue > ?', 1000000)
  .orderBy('Name ASC')
  .limit(10)
  .execute(conn);

Advanced Features

Circuit Breaker

const result = await SalesforceSDK.query(conn, {
  objectName: 'Account',
  fields: ['Id', 'Name'],
  circuitBreakerOptions: {
    failureThreshold: 5,
    resetTimeout: 60000
  }
});

Retry with Exponential Backoff

const result = await SalesforceSDK.query(conn, {
  objectName: 'Account',
  fields: ['Id', 'Name'],
  retryOptions: {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    retryableErrors: ['UNABLE_TO_LOCK_ROW', 'QUERY_TIMEOUT']
  }
});

Field Masking

const result = await SalesforceSDK.query(conn, {
  objectName: 'Contact',
  fields: ['Id', 'Name', 'Email', 'Phone'],
  maskFields: ['Email', 'Phone']
});

// Output: Email will be "em***@example.com", Phone will be "55***7890"

Features

• SQL Injection Prevention: Automatic parameter sanitization
• Circuit Breaker: Prevent cascading failures
• Retry Logic: Exponential backoff for transient errors
• Field Masking: PII protection for sensitive data
• Query Builder: Fluent API for complex queries
• Auto Pagination: Fetch all records automatically
• Performance Monitoring: Track execution times

API Reference

executeQuery(conn, options)

Execute a SOQL query with full feature support.

Parameters:

• conn: JSForce connection instance
• options: Query options object
  • objectName: Salesforce object API name (required)
  • fields: Array of field names to select (required)
  • whereClause: WHERE clause (optional)
  • parameters: Parameter values for ? placeholders (optional)
  • orderBy: ORDER BY clause (optional)
  • groupBy: GROUP BY clause (optional)
  • having: HAVING clause (optional)
  • limit: Maximum number of records (optional)
  • offset: Number of records to skip (optional)
  • autoFetchAll: Fetch all pages automatically (optional)
  • maskFields: Array of fields to mask (optional)
  • retryOptions: Retry configuration (optional)
  • circuitBreakerOptions: Circuit breaker configuration (optional)

Returns: QueryResult object with:

• records: Array of records
• totalSize: Total number of records
• done: Whether all records were fetched
• executionTime: Execution time in milliseconds
• query: Final SOQL query that was executed

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Clean
npm run clean

License

MIT