Skip to content
← Public packages

@kody/salesforce

Salesforce REST helpers for identity, SOQL, multi-org routing, and error investigation.

README.md

88 lines · 4.1 KB · Markdown

@kody/salesforce

Intent

Provide reusable Salesforce REST helpers for Kody agents through saved OAuth integrations. Cover identity checks, SOQL queries, sObject metadata, multi-org routing (explicit integrationName plus an organizationId map), read-only error investigation, and explicitly confirmed record create/update/delete while keeping a generic request escape hatch for the rest of the REST API.

Share this package as https://kody.codes/@kody/salesforce (never a /community/{listing_id} URL).

What it does

  • Verify a connected Salesforce org after OAuth setup
  • Run SOQL queries and inspect sObject metadata
  • Read Contact, Lead, Account, Opportunity, or custom-object records
  • Investigate REST, Flow, or Apex errors without mutating the org
  • Route webhook or triage traffic to the right client org via an org-id map
  • Create, update, or delete records with explicit confirmation
  • Call less-common Salesforce REST paths through the generic request helper

Prerequisites / setup

  1. In Salesforce Setup, create a Connected App (External Client App) with OAuth enabled.
  2. Set the callback URL exactly to https://kody.codes/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://kody.codes/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.

Self-hosted deployments use that deployment's origin plus /connect/oauth as the callback and connect URL, for example https://kody.example/connect/oauth.

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

  1. Agents: see AGENTS.md for import paths, smoke checks, org maps, and mutation snippets.
Multiple orgs

Every export accepts an optional integrationName (default salesforce) so one Kody user can reach several orgs they can OAuth — sandbox and production, or multiple consulting clients — without forking this package and without Kody org workspaces.

  1. Connect each org under its own integration name by changing provider in the connect URL (for example provider=salesforce-acme or provider=salesforce-sandbox with test.salesforce.com endpoints).
  2. Pass that name on every call. Do not rely on the default salesforce name when more than one org is connected.
  3. After the first successful get-user-info / list-orgs, add the exact instance host (acme.my.salesforce.com) to that connection's requiredHosts. Kody host allowlists are exact hostnames; *.salesforce.com in the connect URL is not expanded.

Inbound webhooks are per-user minted URLs. Persist an organizationId → integrationName map in a private package's packageStorage() (live imports of @kody/salesforce cannot use packageStorage). Unknown organization ids should fail closed.

Kody does not add organization workspaces or share client orgs across users. Each consultant uses their own Kody account and only connects orgs they can OAuth.

Done when

  • A Salesforce OAuth integration is connected; login/test host and the exact instance host are approved
  • Smoke test verifies OAuth without returning profile PII
  • Mutations preview with dryRun: true and only run live with confirm: true after you approve the exact sObject/fields; triage-error stays read-only

Docs