Skip to main content

Stack-SDK extension-call pattern

When a project enables an extension, the extension can expose a runtime API that the project's application code calls. This page describes how that call is made today and the typed call pattern the platform is designed to offer on top of it.

1. Status​

The typed factory described in §3, k9o.extension(slug), is a design target. None of the SDKs ships it yet, and no extension-to-extension call is available either. Application code reaches an installed extension's runtime API over HTTP (§2). The SDKs' own clients (createClient and its per-language equivalents) cover the platform's pillars; they do not expose installed extensions.

Extension authors write their extension against @k9o/extensions-sdk. The package named @k9o/extensions on npm is a placeholder and is not the author SDK.

2. Calling an installed extension today​

An installed extension's runtime API is served by the gateway under the project:

<orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug>/api/<apiSlug>

Any HTTP method the extension declares is accepted. The methods, paths and bodies available under <apiSlug> are the extension's own: they are described by the OpenAPI document the extension bundles in its manifest (surfaces.runtime_api, see the Extensions API reference).

3. Design target: the typed installation-instance pattern​

The planned shape is a factory, extension(slug), that returns a typed instance bound to the project's installed-extension context. Its method tree would be generated from the extension's bundled OpenAPI document, so parameter shapes, return types and error variants surface through the language's type system. The design has these properties:

PropertyBehaviour
Project-scoped credentialsThe instance carries the project's credentials transparently, so each call needs no per-call boilerplate
Tier-bound consumption meteringExtension calls compose against the project's billing dimensions, and consumption shows up in the project's billing surface the same way as native API calls
Audit attributionEvery extension call is attributed to the extension in the project's audit ledger

For extensions that ship with the SDK distribution, the typed bindings would be included in the package. For open-ended community extensions, a codegen step run after enabling the extension would produce a local typed module. Inbound webhook handlers would receive a context typed against the extension's declared webhook ingress shape, already verified by the gateway per Security: Webhook signature verification. This page will gain call examples when the SDK methods ship.

4. See also​