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

Start by comparing integrations/github/src/index.ts with the Linear and Slack integrations, then review the required integrations/salesforce/ files. Implement the OAuth flow, Salesforce API utilities, incremental sync, activity conversion, documentation, and README entry described in the issue. Done means the listed Salesforce records and events sync into CORE, including pagination, errors, rate limits, and sandbox support.