Configuration Capability¶

ConfigurationCapability is the contract base for a capability that presents a typed key/value store scoped to a project (feature flags, secrets, service settings). Bind it with a Capability(kind='configuration', handler=...) in the plugin's manifest. The four required methods receive a PluginContext (project identity + resolved options) and the Integration's decrypted credentials dict. One optional method, describe_prefix, receives only the PluginContext.

Surfaces: ui, api.

See Authoring Plugins for the manifest, capabilities, context, credential decryption, and error conventions shared by every plugin.

from imbi.common.plugins import (
    ConfigKey,
    ConfigKeyWithValue,
    ConfigurationCapability,
    ConfigValue,
    PluginContext,
)


class VaultConfiguration(ConfigurationCapability):
    async def list_keys(
        self,
        ctx: PluginContext,
        credentials: dict[str, str],
    ) -> list[ConfigKey]:
        ...

    async def get_values(
        self,
        ctx: PluginContext,
        credentials: dict[str, str],
        keys: list[str] | None = None,
    ) -> list[ConfigKeyWithValue]:
        ...

    async def set_value(
        self,
        ctx: PluginContext,
        credentials: dict[str, str],
        key: str,
        value: ConfigValue,
    ) -> ConfigKey:
        ...

    async def delete_key(
        self,
        ctx: PluginContext,
        credentials: dict[str, str],
        key: str,
    ) -> None:
        ...

Method contracts¶

• list_keys — return every key visible to the project. Do not inline values; use get_values for that. Populate last_modified when the upstream system exposes it.
• get_values — when keys is None, return values for every visible key (mirroring list_keys); otherwise return only the requested subset. Missing keys should be omitted, not raised.
• set_value — create or update. The returned ConfigKey should reflect the persisted state, including last_modified.
• delete_key — idempotent; deleting an absent key should not raise.
• describe_prefix (optional, default None) — return the resolved key prefix that the capability reads and writes under. The other methods return keys with this prefix removed, and capability options can contain variables (for example ${project_type_slug}) that only the plugin can expand. The host returns this value to the UI so it can show the full key path. This method is synchronous. Return None when the capability has no prefix.

Data types and secrets¶

manifest.data_types tells the host which ConfigValue.data_type strings are valid, and which represent secret material (and therefore should be redacted in UI and audit logs). Mark a ConfigKey / ConfigKeyWithValue as secret=True when the key's data type is one of the manifest's secret types; the host uses this to gate read access and to redact values.

Hints¶

• cacheable — the host may cache reads from this capability.

API reference¶

describe_prefix(ctx: PluginContext) -> str | None

1278
1279
1280
1281
1282
1283
1284
1285
1286

def describe_prefix(self, ctx: PluginContext) -> str | None:
    """The resolved key prefix the capability reads and writes under.

    Keys are returned with this prefix stripped, so the UI has no way
    to reconstruct it — capability options may reference variables
    (e.g. ``${project_type_slug}``) that only the plugin can expand.
    Returns ``None`` for capabilities that have no prefix.
    """
    return None