WordPress introspection

The generated introspection types the routes published by the plugins active on your WordPress site: the WP_* types and an endpoints descriptor map, built from GET /kizlo/v1/introspect. It carries no request logic. The callable client is assembled from it, and you reach it through context.wordpress in a procedure, event handler, fixture, or other server-side Kizlo code.

Generate the introspection

kizlo init and kizlo create write a stub at <dir>/server/generated/introspection.ts. The first generation replaces it with endpoints fetched from GET /kizlo/v1/introspect on your configured WordPress site.

For the default dir: "src/lib/kizlo", the file lives at src/lib/kizlo/server/generated/introspection.ts. A package without a Kizlo server can set dir: { introspection } and receives <introspection>/introspection.ts instead.

What the stub means

The stub marks the endpoint tree as any so a new project compiles before it has connected to WordPress. It does not mean that WordPress has no routes, and it does not provide endpoint definitions at runtime.

Run kizlo generate before relying on endpoint completion or checking a production build. The generated file replaces any with the routes, inputs, results, and error codes published by the active site.

Read the endpoint tree

Each API ID segment becomes a nested client key. Kizlo camelizes every segment and operation name for the generated TypeScript member.

The input object combines the fields from the route declaration. Path parameters are inserted into the URL; the remaining fields become query parameters for reads or a request body for writes. Required fields make the first argument required, while an endpoint with no required fields can be called without one.

const response = await context.wordpress.postTypes.post.retrieve({
  identifier: "hello-world",
})

if (response.error) {
  context.logger.error(response.error.message)
  throw response.error
}

return response.data

An identifier on a managed post type or taxonomy accepts a numeric ID or slug as a string.

Call an endpoint the tree does not have

The file describes one WordPress at one moment. Switch off API access for a post type, deactivate the plugin that serves a route, or generate against a different site, and your code is left calling a path the file no longer has.

The call resolves to a failure instead of throwing, carrying the rest_no_route code that is already in every endpoint's error union. Nothing is sent, so the check you write for any failed request covers it.

const response = await context.wordpress.postTypes.post.list()

// response.error.code
// "rest_no_route"

// response.error.message
// No endpoint at "postTypes.post.list" in this project's generated client, so nothing was sent.
// Run `kizlo generate` against the WordPress you are connecting to.

To branch before calling, ask the client what it carries: "woocommerce" in context.wordpress.

Override one call

Pass request-specific options as the second argument. They affect this invocation without changing the endpoint definition or transport defaults.

const controller = new AbortController()

await context.wordpress.postTypes.post.retrieve(
  { identifier: "42" },
  {
    headers: { "X-Request-Source": "featured" },
    signal: controller.signal,
    timeout: "5 seconds",
  },
)

See WP_CallOptions for the option types.

Name endpoint shapes

Use the dotted client path to reuse a generated shape without importing the generated file:

import type { WP_EndpointData, WP_EndpointInput, WP_EndpointResult } from "kizlo"

type Post = WP_EndpointData<"postTypes.post.retrieve">
type PostListInput = WP_EndpointInput<"postTypes.post.list">
type PostResult = WP_EndpointResult<"postTypes.post.retrieve">

The reference pages cover WP_EndpointData, WP_EndpointInput, and WP_EndpointResult.

Add a route the plugin does not own

An integration plugin can add a core or third-party route to the document without registering a new WordPress endpoint. Register its reusable response shapes with kizlo_register_route_schema, then describe each operation with kizlo_register_route_spec.

When the upstream API already exposes WordPress-style schemas, derive the declaration with kizlo_translate_spec_properties or kizlo_translate_spec_schema. Regenerate the introspection after the companion plugin is active, then call the new API ID and operation through the naming rules above.