@kody/salesforce

@kody/salesforce

Intent

Provide reusable Salesforce REST helpers for Kody agents through a saved salesforce OAuth integration. Cover identity checks, SOQL queries, sObject metadata, and explicitly confirmed record create/update/delete while keeping a generic request escape hatch for the rest of the REST API.

When To Use

• Verify a connected Salesforce org after OAuth setup
• Run SOQL queries and inspect sObject metadata
• Read Contact, Lead, Account, Opportunity, or custom-object records
• Create, update, or delete records with explicit confirmation
• Call less-common Salesforce REST paths through the generic request helper

Required Setup

1. In Salesforce Setup, create a Connected App (External Client App) with OAuth enabled.
2. Set the callback URL exactly to https://heykody.dev/connect/oauth.
3. Enable OAuth scopes such as api, refresh_token, and offline_access (add more only if your workflows need them).
4. Connect the integration in Kody:

Production:

https://heykody.dev/connect/oauth?provider=salesforce&authorizeUrl=https%3A%2F%2Flogin.salesforce.com%2Fservices%2Foauth2%2Fauthorize&tokenUrl=https%3A%2F%2Flogin.salesforce.com%2Fservices%2Foauth2%2Ftoken&apiBaseUrl=https%3A%2F%2Flogin.salesforce.com&scopes=api%20refresh_token%20offline_access&flow=confidential&allowedHosts=login.salesforce.com%2C*.salesforce.com%2C*.force.com%2C*.my.salesforce.com

Sandbox: use test.salesforce.com in place of login.salesforce.com for authorizeUrl, tokenUrl, apiBaseUrl, and allowedHosts.

The package discovers each org's instance URL from Salesforce userinfo, so API calls go to the connected org rather than the login host.

Safety

Mutating helpers require confirm: true. Pass dryRun: true to inspect a request without sending it. The generic request helper treats GET requests and known read-only paths as safe; all other methods require confirmation.

Exports

• kody:@kody/salesforce — package overview and setup guidance
• kody:@kody/salesforce/smoke-test — verify OAuth without returning profile PII
• kody:@kody/salesforce/get-user-info — connected user and org identity
• kody:@kody/salesforce/query — run a SOQL query
• kody:@kody/salesforce/list-sobjects — list available sObjects
• kody:@kody/salesforce/describe-sobject — describe one sObject
• kody:@kody/salesforce/get-record — fetch one record by type and id
• kody:@kody/salesforce/create-record — create a record
• kody:@kody/salesforce/update-record — update a record
• kody:@kody/salesforce/delete-record — delete a record
• kody:@kody/salesforce/request — generic authenticated REST request

Examples

import query from 'kody:@kody/salesforce/query'

export default async function main() {
	return await query({
		q: 'SELECT Id, Name, Email FROM Contact ORDER BY LastModifiedDate DESC LIMIT 10',
	})
}

import createRecord from 'kody:@kody/salesforce/create-record'

export default async function main() {
	return await createRecord({
		sobject: 'Lead',
		fields: {
			FirstName: 'Ada',
			LastName: 'Lovelace',
			Company: 'Analytical Engines',
			Email: 'ada@example.com',
		},
		dryRun: true,
	})
}

Set confirm: true only after the user has explicitly approved the exact mutation target and field values.