Separate what you need from who provides it
An application need, a provider’s abilities and its connection method answer different questions. Wildo records each explicitly, so choosing an email service is distinct from enabling email or describing how that service receives a message.
You declare the providers the application uses. Wildo connects their declared abilities to the framework features that consume them.
Example — An email service with a clear role
A product needs transactional email. Its backend declares a provider that supports that need and the email connection contract. The same product can use a different provider for language models without coupling those decisions.
For engineers
Read the declaration as three separate decisions
Wonder Todos enables EngineCapability.EMAIL_TRANSACTIONAL in engineCapabilities, then declares Resend under providers.scopes.backend.providers. This selection from that declaration, with Resend’s inbound-email capability and protocols omitted, states what that runtime may use for sending:
resend: {
engineCapabilities: [EngineCapability.EMAIL_TRANSACTIONAL],
providerCapabilities: ['EMAIL_TRANSACTIONAL'],
protocols: ['EMAIL_PROVIDER'],
},
The engine capability names the framework need. The provider capability records an ability the provider contributes. The protocol selects its executable connection contract. defineSaaSProviders validates declarations against the discovered catalogue; the backend registry filters them again for its active scope.
Understand where the ability comes from
The provider module owns the corresponding ability declaration. Resend’s backend module includes:
Selected from resend.backend.module.ts; a comment and the webhook-secret and development-override entries of the secrets contract are omitted.
providerCapabilities: [
BUILTIN_PROVIDER_CAPABILITY.EMAIL_TRANSACTIONAL,
BUILTIN_PROVIDER_CAPABILITY.EMAIL_INBOUND,
],
secretsContract: {
apiKey: {
envVarName: "RESEND_API_KEY",
required: true,
description: "Resend API credential for email delivery, receiving and domains."
},
},
The module’s protocol binding then supplies the email implementation. The application supplies the credential through its supported secret configuration and selects the provider for the enabled capability. The shared projection map derives engine capabilities from provider abilities rather than maintaining a second vendor-specific slot list.
Know when a capability selection is the wrong abstraction
| Integration | How it is addressed |
|---|---|
| Transactional email or a language model | A provider serving the enabled engine capability in the runtime scope |
| A vendor-specific REST operation, such as creating an Asana task | The provider reference and operation the application calls |
| A business system such as an ERP, read or written as a resource | The named system-of-record instance the resource binding’s system field points at |
| Organizations or application language support | Engine-implemented activation, not an external provider selection |
A REST vendor module can therefore declare empty capability lists and still expose its REST protocol. Do not invent a slot merely to make every integration look alike. The capability vocabulary is closed: an application cannot add its own capability names, so a need it does not name is a decision to widen the framework’s vocabulary together with the code that consumes it. The capability map now checks that each engine capability is either mapped or explicitly engine-owned; adding an unaccounted capability is a compile-time error.
Provider tier and origin are additional declared metadata. They describe the provider’s role and provenance, not whether your application has enabled or configured it. Keep those questions separate when tracing why a provider is available.