Skip to main content

Extension typing model

This page documents the typing mechanism behind the Stack-SDK extension-call pattern. It is a design target: no SDK ships typed extension bindings yet, and application code reaches an installed extension over its HTTP route in the meantime (see the pattern page, §2).

1. One source of truth: the extension's OpenAPI document​

Every extension that exposes a runtime API declares it in its manifest under surfaces.runtime_api (see Extensions API reference §2.3): a mount prefix plus a bundled OpenAPI spec. For each operation the document gives:

  • the path and HTTP method, which shape the typed call's resource segment and its read or write semantics;
  • the parameter and response shapes, which become the typed call's parameters, return type and error variants;
  • a permission_scope, which cross-references a manifest-declared permission. The gateway enforces that grant before the request reaches the extension.

There is no separately maintained type declaration. An extension author who changes a route changes the OpenAPI document in the same version bump, and the typed binding is regenerated from it.

2. Codegen pipeline​

The design has the typing pipeline run at SDK build time:

  1. The extension manifests of the curated extensions are collected from the platform's catalogue.
  2. Each extension's bundled OpenAPI document is read.
  3. One typed declaration is generated per extension, exposing its method tree.
  4. A registry is assembled that maps each extension slug to its generated type, so that a call with a slug literal infers the right return type and a slug that matches no entry is a compile-time error.
  5. The registry and the per-extension declarations ship with the SDK package.

Extensions outside the curated set are an open-ended catalogue, so their typed bindings would be generated on the consumer's machine instead: after enabling the extension on a project, a codegen step fetches the extension's OpenAPI document from the platform and writes a local typed module. The consumer's build can run that step once per extension and on each extension version update.

3. Per-language parity​

The same model is meant to carry through each SDK family's own idioms: generated types and interfaces in the statically typed languages, generated stubs or typed hashes in the dynamic ones. The OpenAPI document is the canonical source, so the same extension would have the same call shape in every language, modulo language casing. Mobile SDKs are limited to Gate, Kibo and embeddings today and are outside this design until that changes.

4. See also​