New Integration: Salesforce

Description

Add Salesforce integration to sync CRM data including leads, contacts, accounts, opportunities, and activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - Similar webhook-driven event system
• integrations/linear/ - Project management integration
• integrations/slack/ - For messaging reference

Required Files Structure

integrations/salesforce/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Salesforce API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Salesforce API Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Grant)
• Authorization URL: https://login.salesforce.com/services/oauth2/authorize
• Token URL: https://login.salesforce.com/services/oauth2/token
• Revoke URL: https://login.salesforce.com/services/oauth2/revoke
• Required scopes:
  • api - Access and manage data via APIs
  • refresh_token (or offline_access) - Allow refresh tokens for offline access
  • id - Access identity URL service
  • chatter_api - Access Chatter REST API (optional)
  • full - Full access to all data (alternative to granular scopes)

Base URL

• https://{instance}.salesforce.com/services/data/v66.0 (Spring '26 - latest)
• Instance URL is returned in the OAuth token response

Key Endpoints

• GET /services/data/ - List available API versions
• GET /services/data/v66.0/sobjects/ - List all sObjects
• GET /services/data/v66.0/sobjects/{sObject}/describe - Describe an sObject
• GET /services/data/v66.0/sobjects/{sObject}/{id} - Get a record
• POST /services/data/v66.0/sobjects/{sObject}/ - Create a record
• PATCH /services/data/v66.0/sobjects/{sObject}/{id} - Update a record
• DELETE /services/data/v66.0/sobjects/{sObject}/{id} - Delete a record
• GET /services/data/v66.0/query/?q={SOQL} - Execute SOQL query
• GET /services/data/v66.0/queryAll/?q={SOQL} - Query all (including deleted/archived)
• GET /services/data/v66.0/search/?q={SOSL} - Execute SOSL search
• GET /services/data/v66.0/recent - Recently viewed records
• GET /services/data/v66.0/limits - API usage limits
• GET /services/data/v66.0/sobjects/{sObject}/updated/?start={start}&end={end} - Get updated records in time range
• GET /services/data/v66.0/sobjects/{sObject}/deleted/?start={start}&end={end} - Get deleted records in time range

Key sObjects

• Lead - Sales leads
• Contact - Contacts
• Account - Companies/organizations
• Opportunity - Deals/opportunities
• Task - Tasks and activities
• Event - Calendar events
• Case - Support cases
• Note - Notes

Events to Track

1. Lead Events

   • Lead created
   • Lead updated (status change, assignment)
   • Lead converted to opportunity
   • Lead deleted

2. Contact/Account Events

   • Contact created/updated/deleted
   • Account created/updated/deleted

3. Opportunity Events

   • Opportunity created
   • Opportunity stage changed
   • Opportunity won/lost
   • Opportunity amount updated
   • Opportunity deleted

4. Task/Activity Events

   • Task created/completed
   • Event created/updated
   • Call logged
   • Email logged

5. Case Events

   • Case created
   • Case status changed
   • Case closed

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts (handle instance URL from token response)
• Create Salesforce API utilities in utils.ts with SOQL query builder
• Implement sync logic in schedule.ts using updated/deleted record endpoints for incremental sync
• Convert Salesforce records and events to CORE activity format
• Handle pagination for large query results (nextRecordsUrl)
• Add error handling and rate limiting
• Support Salesforce sandbox environments (test.salesforce.com)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Salesforce REST API v66.0 (Spring '26) is the latest version
• Instance URL varies per org (e.g., na1.salesforce.com, eu5.salesforce.com) - extracted from OAuth response
• Use updated and deleted endpoints for efficient incremental sync
• SOQL supports complex queries with relationships (similar to SQL JOINs)
• Salesforce has strict API call limits based on org edition (e.g., 15,000/day for Enterprise)
• Sandbox environments use test.salesforce.com for OAuth instead of login.salesforce.com
• Refresh tokens do not expire unless revoked
• Bulk API available for large data volumes (separate endpoint)

Resources

• Salesforce REST API Developer Guide (v66.0)
• Salesforce OAuth Authorization
• Salesforce OAuth Scopes
• Execute SOQL Queries
• Salesforce REST API PDF (v66.0, Spring '26)

Labels

enhancement, integration, new-feature