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. All four methods receive a PluginContext (project identity + resolved options) and the Integration's decrypted credentials dict.

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.

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

1093
1094
1095
1096
1097
1098
1099
1100
1101

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