Salesforce Typed Adapter and Client-Library Boundary
Overview
Contain library churn and org-specific schema behind a small adapter whose types, API version, permissions, retries, and evidence are explicit.
Prerequisites
- Repository, runtime, supported environments, and selected Salesforce library or CLI
- Current dependency lock, org schema evidence, API support policy, and error samples
- Application, Salesforce platform, security, and data owners
Tool Discipline
Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.
Current Contract
Salesforce publishes versioned API contracts, while third-party client libraries have independent release and support policies. Object and field shapes remain customer-specific, so generated or handwritten types must be tied to dated metadata evidence.
Authentication
Accept an authenticated client or secret reference from the approved authorization layer. The adapter must not invent a password fallback, persist tokens, broaden scopes, or choose a production org implicitly.
Instructions
- Inventory direct Salesforce calls, library versions, API versions, objects, fields, mutations, retries, and error handling.
- Define a narrow adapter interface for identity, metadata discovery, reads, bounded writes, async jobs, and limits.
- Bind types to dated object metadata or a governed schema snapshot and label nullable, encrypted, formula, and inaccessible fields.
- Centralize pagination, request IDs, timeouts, idempotency keys or external IDs, error normalization, and redaction.
- Add contract fixtures for success, partial failure, token expiry, permission denial, schema drift, limits, and timeouts.
- Test the adapter without a live org, then run approved read-only and sandbox mutation probes.
- Migrate callers incrementally and retain a reversible compatibility boundary until evidence is complete.
Approval Boundaries
Do not upgrade dependencies, change API versions, regenerate broad schemas, or perform live writes without code owner, platform owner, and data owner approval.
Output
Return the adapter contract, dependency and API matrix, schema provenance, fixture coverage, migration plan, live probe receipt, and rollback boundary.
Error Handling
| Condition | Response |
|---|---|
| Library behavior differs from Salesforce documentation | Pin the discrepancy, reproduce at the raw API boundary, and escalate upstream before broad rollout. |
| Schema snapshot is stale | Block generated-type use until metadata is refreshed and reviewed. |
| Caller bypasses the adapter | Fail the policy check or document a time-bounded exception with an owner. |
Example
A redacted completion receipt might look like this:
adapter=SalesforceGateway; api=discovered-supported; schema=dated; fixtures=8; sandbox-write=approved-pass; bypasses=0
Resources
Next Steps
Run the workflow first in the lowest-risk authorized org and preserve its redacted receipt. Schedule a review against the next Salesforce seasonal release and the customer change calendar.