Skip to content

Public API Reference (1.x)

This page enumerates the stable public API covered by the versioning & stability policy. Anything not listed here — and anything named with a leading underscore — is internal and may change without a major version bump.

node_wire_runtime

Stable top-level exports (node_wire_runtime.__all__):

Connector authoring

  • BaseConnector, RestConnector — base classes for connectors (RestConnector adds the shared HTTP-request scaffolding used by OpenAPI-generated connectors).
  • RestResponseOutput — shared output model for RestConnector-based connectors.
  • RestEnvelopeError — raised by RestConnector when a 2xx response's declared success flag (envelope_ok_field, e.g. Slack's ok) reports failure.
  • get_connector_registry() — returns a copy of the connector-id → class registry.
  • nw_action, sdk_action — action decorators.
  • SdkActionSpec, default_build_kwargs, default_resolve_method, default_invoke, execute_spec_in_thread, execute_spec_async.
  • navigate_resource — deprecated; unused by the execute path, kept for backward compatibility.
  • NestedConnectorActionError.

Responses & errors

  • ConnectorResponse
  • ErrorCategory
  • ErrorMapper
  • ErrorCode — the runtime-wide error codes; node_wire_runtime.errors.CATALOGUE gives each one's category.
  • NodeWireError — NodeWireError(code, message, *, details=None): raise it for a failure outside the connector (bad arguments, no tenant, unknown config); a ValueError, with its category from the catalogue. node_wire_runtime.errors.reject(exc, ...) turns any such failure into a logged, traced ConnectorResponse, and error_text(response) renders it as CODE [CATEGORY]: message (trace_id=...).

Authentication

  • AuthProvider (base), NoAuthProvider, StaticTokenAuthProvider, ApiKeyQueryAuthProvider, OAuth2AuthProvider, ServiceAccountAuthProvider.
  • CallerIdentity, build_caller_identity.

Policy

  • PolicyHook, PolicyDenied.

Tenancy (host apps)

  • resolve_tenant_id, tenant_from_headers, MissingTenantError
  • TenantMismatchError — factory instance tenant disagrees with run(tenant_id=...)
  • TenantIdentityMismatchError — a caller-supplied tenant (header/session) disagrees with the authenticated JWT's tenant claim
  • DEFAULT_TENANT (__default__)
  • effective_run_tenant_id, normalize_tenant_id, tenants_equivalent — helpers for the pin contract

Runtime config store

  • ConnectorConfigStore, ConfigRecord — the per-(tenant, connector, config_name) runtime config store backing multi-tenant named configs.
  • ConfigNotFoundError, ConfigNameConflictError, DefaultDeletionError — config-store error types.

Secrets

  • SecretProvider (base), EnvSecretProvider, SecretNotFoundError, SecretProviderError.
  • TenantSecretProvider, TenantSecretNotFoundError — tenant-scoped secret resolution.

Streaming

  • StreamSignal, stream_completion_log, resolve_stream_buffer_ms, BufferedStreamIterator.

Version

  • __version__ — module attribute (not itself listed in __all__, but always accessible and stable)

Connector contract (extensibility API)

Connector authors depend on these stable modules:

  • node_wire_runtime.base_connector — BaseConnector, action decorators.
  • node_wire_runtime.auth.base — AuthProvider interface.
  • node_wire_runtime.secrets.base — SecretProvider interface.

Connector-specific argument normalizers are not part of the stable surface. They live in the connector that owns them (for example node_wire_google_drive.normalizers). The removal of node_wire_runtime.mcp_contract is recorded in CHANGELOG.md.

Connectors register via the node_wire.connectors entry-point group.

Bootstrap (not in __all__): node_wire_runtime.connector_registry.auto_register() loads entry points at process startup (requires NW_ALLOWED_CONNECTORS). In-process usage typically goes through bindings.factory.ConnectorFactory after auto_register(), not direct registry access.

Host logging (not in __all__, since 1.1.0): generated MCP hosts call these at startup, so their signatures are stable.

  • node_wire_runtime.host_logging.configure_host_logging(service_name, *, level="INFO") — console handler that prints the runtime's extra fields (trace_id, error_code, …), redaction, and OpenTelemetry export when an OTLP endpoint is set. Used by nw-mcp-builder hosts.
  • node_wire_runtime.host_logging.install_redaction_and_telemetry(service_name) — the same without touching handlers or formatters, for hosts that own their console format.
  • node_wire_runtime.host_logging.ExtraFieldsFormatter, otlp_configured().

node_wire_toolhive

Stable exports (node_wire_toolhive.__all__) that stacklok-built MCP servers import: NodeWireClient, NodeWireToolError, RelayAuthProvider, relay_auth_provider_hook, register_config_tools, report_call_errors(mcp, client) and init_telemetry(service_name) (both since 1.1.0).

Wire contracts

  • REST — routes and request/response schemas served by the API binding (Swagger UI at /docs).
  • gRPC — the Connector service defined by the committed protobuf contract.
  • MCP — tool manifests exposed by the MCP servers (nw-*).

Configuration

Console scripts

node-wire, nw-google-drive, nw-smartonfhir-epic, nw-smartonfhir-cerner, nw-smtp, nw-stripe, nw-salesforce, nw-slack.