@zapier/kitcore

A TypeScript framework for building plugin-driven SDKs.

kitcore lets you assemble an SDK out of small, independent units called plugins. A plugin is shaped like an ES module: it has an identity, declares the other plugins it imports, and exports named members. You compose plugins by importing and re-exporting them, and createSdk materializes the whole graph into a finished, fully typed SDK object.

The design goals:

• Fully typed authoring. Inside a method, both its private state and its imports are inferred with no manual annotations.
• Introspectable without running anything. A plugin's contract (its methods, input schemas, output modes, metadata) is plain data, so a CLI, MCP server, or docs generator can walk it without invoking your code.
• Low ceremony. No base classes, no decorators, no DI container. You write functions and arrays.

Install

npm install @zapier/kitcore zod

zod is a peer dependency (used for input validation and schema-driven typing).

Quick start

The smallest SDK is a single method. defineMethod describes it; createSdk builds it.

import { z } from "zod";
import { defineMethod, createSdk } from "@zapier/kitcore";

const greet = defineMethod({
  name: "greet",
  inputSchema: z.object({ name: z.string() }),
  run: ({ input }) => `Hi ${input.name}`,
});

const sdk = createSdk(greet);
sdk.greet({ name: "Ada" }); // "Hi Ada"

inputSchema is optional. When present it validates the call at the boundary and types input for you, so run needs no annotations.

Plugins are modules

There are four kinds of plugin, and an SDK is just a materialized plugin:

• Method (defineMethod) — a leaf that is a function.
• Property (defineProperty) — a leaf that is a value.
• Hook (defineHook) — a leaf contributing cross-cutting behavior (see Hooks).
• Aggregate (definePlugin) — re-exports other plugins under binding names.

A plugin declares imports (an array of the plugins it depends on) and receives them as a flat imports bag, with each import bound under its own name. The two ends share the word the way ES modules do: import { x } from "y" is the declaration, x is the binding.

const transport = defineMethod({
  name: "transport",
  run: ({ input }) => fetch(input.url),
});

const getUser = defineMethod({
  name: "getUser",
  imports: [transport], // depend on transport
  run: ({ imports, input }) => imports.transport({ url: `/users/${input.id}` }),
});

Importing a plugin pulls it into the graph but keeps it private. It only becomes part of the SDK surface if an aggregate exports it.

Composing an SDK

definePlugin builds an aggregate. Its exports array decides the public surface: a leaf binds under its own name, and a nested aggregate spreads its bindings.

import { definePlugin, createSdk } from "@zapier/kitcore";

const api = definePlugin({
  name: "api",
  exports: [getUser, fetch], // surface getUser + fetch; transport stays private
});

const sdk = createSdk(api);
sdk.getUser({ id: 1 });
sdk.fetch(url);
sdk.transport; // undefined — imported by getUser, never exported

Subsetting and renaming with selectExports

selectExports is the { a, b as c } clause. It picks a subset of a module's exports and optionally renames them. It works the same on the exports side (what you re-export) and the imports side (what a body sees).

import { selectExports } from "@zapier/kitcore";

const sdk = createSdk(
  definePlugin({
    name: "users",
    // re-export getUser under its own name, and listUsers as `listAll`
    exports: [selectExports(users, "getUser", { listAll: "listUsers" })],
  }),
);
sdk.getUser({ id: 1 });
sdk.listAll();

If two different plugins try to bind the same name, kitcore throws and points you at selectExports to rename one. Composition is dependency-based, so registration order never matters.

State and effects: setup

setup is a per-build constructor. It runs once when createSdk materializes the plugin (dependencies first), may perform side effects, and returns private state handed to run as bag.state.

const counter = defineMethod({
  name: "next",
  setup: () => ({ n: 0 }), // runs once at createSdk
  run: ({ state }) => ++state.n, // same state across calls
});

const sdk = createSdk(counter);
sdk.next(); // 1
sdk.next(); // 2

setup can read imports, so state can be built from dependencies. Because state lives behind setup, several small "state plugins" can each own a slice instead of one monolith.

Properties

A property is a value rather than a function. It can be a static value, or a live get re-derived on every read, with an optional setup building the state get returns. So setup + get mirrors a method's setup + run.

import { defineProperty } from "@zapier/kitcore";

// static value
const version = defineProperty({ name: "version", value: "1.0.0" });

// built once, returned live
const apps = defineProperty({
  name: "apps",
  imports: [runAction, fetch],
  setup: ({ imports }) => buildAppsProxy(imports), // once at createSdk
  get: ({ state }) => state, // returned per read
});

Use setup + get when construction is expensive and should happen once; compute directly in get (no setup) when the value is cheap and you want it fresh on each access.

Sharing state between plugins

State doesn't have to live inside one plugin. A property whose setup builds a value once becomes a small state plugin: every plugin that imports it receives the same instance, so state is shared without a global or a monolithic context object.

// A state plugin: one Map, built once at createSdk.
const cache = defineProperty({
  name: "cache",
  setup: () => new Map<string, unknown>(),
  get: ({ state }) => state, // every importer gets the same Map
});

const write = defineMethod({
  name: "write",
  imports: [cache],
  run: ({ imports, input }) => imports.cache.set(input.key, input.value),
});

const read = defineMethod({
  name: "read",
  imports: [cache],
  run: ({ imports, input }) => imports.cache.get(input.key),
});

const sdk = createSdk(definePlugin({ name: "store", exports: [write, read] }));
sdk.write({ key: "a", value: 1 });
sdk.read({ key: "a" }); // 1 — the same Map, shared across both methods

Prefer several focused state plugins over one big shared object: each owns a slice, dependents declare exactly the state they touch, and you can swap or mock one slice in tests without disturbing the rest.

Output modes

A method's output mode shapes what run returns into the public surface:

// raw (default): the surface is whatever run returns
const transport = defineMethod({
  name: "transport",
  run: ({ input }) => fetch(input.url),
});

// item: run returns the { data } envelope itself (data and nothing else),
// symmetric with list's page shape
const getApp = defineMethod({
  name: "getApp",
  output: "item",
  run: () => ({ data: app }),
});
const { data } = await sdk.getApp({ app: "slack" });

// list: run returns one page; the surface is a paginated iterable
const listApps = defineMethod({
  name: "listApps",
  output: { type: "list", adaptPage, defaultPageSize: 100 },
  run: ({ input }) => api.get("/apps", { offset: input.cursor }),
});
for await (const app of sdk.listApps().items()) {
  /* every app across pages */
}

Positional methods

By default a method takes a single options object. positional projects named input keys onto an ordered argument list for the public call, while validation, middleware, and run still see the canonical { input }.

const fetchMethod = defineMethod({
  name: "fetch",
  inputSchema: z.object({ url: z.string(), init: z.object({}).optional() }),
  positional: ["url", "init"],
  run: ({ input }) => doFetch(input.url, input.init),
});
sdk.fetch("https://example.com", { method: "GET" });

Hooks: wrap and observe

Cross-cutting behavior lives in a hook (defineHook), a fourth kind of leaf with two faces.

wrap is targeted middleware. An entry is keyed by the import binding it wraps and receives { imports, next, input }. It must preserve the target's contract (enforced by the types), so it cannot change the public signature.

import { defineHook } from "@zapier/kitcore";

const auth = defineHook({
  name: "auth",
  imports: [transport, credentials],
  wrap: {
    transport: ({ imports, next, input }) =>
      next({
        ...input,
        headers: withAuth(input.headers, imports.credentials()),
      }),
  },
});

const retry = defineHook({
  name: "retry",
  imports: [transport, auth], // import auth so retry nests around it
  wrap: { transport: ({ next, input }) => withRetry(() => next(input)) },
});

A method that imports transport knows nothing about auth or retry; it just calls imports.transport(...) and the chain runs automatically. Nesting follows the dependency edges (retry imports auth, so it wraps around it), not registration order, and next(input) runs the next layer.

observe is fire-and-forget: onMethodStart / onMethodEnd observers that the method boundary fires around every SDK method (input carries the lifecycle context: methodName, args, durationMs, error, ...). Observers run defensively, so a throwing observer never breaks the observed call, and an observer that itself calls SDK methods does not re-trigger itself. setup gives the hook private state, delivered to each observer.

const telemetry = defineHook({
  name: "telemetry",
  setup: () => ({ events: [] as string[] }),
  observe: {
    onMethodEnd: ({ input, state }) =>
      state.events.push(`${input.methodName}:${input.error ? "err" : "ok"}`),
  },
});

A hook joins the graph like any other plugin: import or export it from an aggregate.

Dependency injection

A plugin "names what it needs and receives it" without knowing who supplied it. That makes test doubles and configured providers trivial: register a real implementation under the same id and dependents get it transparently. This is the normal way one plugin reaches another, import the plugin, read it from the imports bag.

Configuration

Runtime values (an options object, a configured client) enter through createSdk's configuration map, keyed by plugin id. Each entry materializes as a value property with that id, satisfying a declareProperty / declareOptionalProperty stand-in — so plugins read configuration through imports like any other dependency, and tests inject doubles the same way.

import { declareOptionalProperty } from "@zapier/kitcore";

const configRef = declareOptionalProperty<"config", { pageSize?: number }>({
  id: "config",
});

const listThings = defineMethod({
  name: "listThings",
  imports: [configRef],
  run: ({ imports }) => api.list({ pageSize: imports.config?.pageSize ?? 10 }),
});

const sdk = createSdk(listThings, {
  configuration: { config: { pageSize: 50 } },
});

Extending a built SDK

addPlugin materializes a plugin into an already-built SDK in place. A TypeScript assertion-function signature widens the existing binding to include the new plugin's contributions, so you don't need a new variable.

import { addPlugin } from "@zapier/kitcore";

addPlugin(sdk, defineMethod({ name: "ping", run: () => "pong" }));
sdk.ping(); // "pong", typed

Teardown

dispose is setup's dual: a leaf that owns a resource declares one, receiving { imports, state, input }. disposeSdk(sdk, input?) runs every disposer in reverse build order (dependents before their dependencies) and is idempotent; input is forwarded to each disposer (e.g. { exitCode } from a CLI shutdown).

import { disposeSdk } from "@zapier/kitcore";

const emitter = defineProperty({
  name: "emitter",
  setup: () => createEmitter(),
  get: ({ state }) => state,
  dispose: ({ state }) => state.close(),
});

// at shutdown
await disposeSdk(sdk, { exitCode: 0 });

Introspection

Re-export the built-in getRegistryPlugin to put a getRegistry() method on the SDK. It reports the live surface as plain data (one entry per binding, with the leaf's metadata), which is what drives generated docs, CLI commands, and MCP tools.

import { getRegistryPlugin } from "@zapier/kitcore";

const sdk = createSdk(
  definePlugin({ name: "api", exports: [greet, getRegistryPlugin] }),
);

const registry = sdk.getRegistry();
registry.functions; // [{ name, description, inputSchema, ... }]
registry.categories; // grouped for menus / docs

Because the registry reads the surface at call time, it also reflects anything added later with addPlugin.

Resolving inputs: controllers

A method's inputSchema says what a complete call looks like, but a caller often starts with only part of it. A resolution controller is a sibling layer over a built SDK that turns a partial input into a complete, validated one, asking a host (a CLI prompt, a web form, an agent) for each missing piece only when it has to. The SDK surface is untouched; the controller reads its schemas and resolvers and drives them.

You make a parameter resolvable by attaching a defineResolver to it on the method. A resolver can offer a static enum (derived from the schema), fetch a dynamic list (with pagination and search), resolve without a prompt (a configured default), or describe an object/array to fill in field by field.

import { defineMethod, defineResolver, createSdk } from "@zapier/kitcore";

const appResolver = defineResolver({
  // a paginated, searchable picker
  listItems: ({ input, search, cursor }) => api.listApps({ search, cursor }),
  prompt: ({ items }) => ({
    message: "Which app?",
    choices: items.map((a) => ({ label: a.title, value: a.key })),
  }),
});

const runAction = defineMethod({
  name: "runAction",
  inputSchema: z.object({ app: z.string(), action: z.string() }),
  resolvers: { app: appResolver },
  run: ({ input }) => api.run(input),
});

createController(sdk) exposes two faces over the same engine.

Wizard face: resolve

resolve is in-process sugar: it loops the resolution against an answer callback and returns the finished input. The callback's only job is to render a question and return the chosen action; all resolution logic (fetching, pagination, search, validation, nesting) stays in the engine.

const controller = createController(sdk);

const input = await controller.resolve({
  method: "runAction",
  input: { action: "send_message" }, // seed what you already have
  answer: async ({ state, result }) => {
    // render result.question (a select / input / collection) however you like,
    // then map the user's choice back to an action:
    return { type: "choose", value: "slack" };
  },
});

await sdk.runAction(input); // complete + validated

Serializable protocol: start / step

For a host that spans a client/server boundary (web, agent, MCP), drive the protocol directly. start returns the first { state, result }; you render result, then send the user's action plus the state back through step. state is plain JSON, so it round-trips over the wire with no live objects to keep alive between turns.

let { state, result } = await controller.start({ method: "runAction" });
while (result.status === "ask") {
  const action = await renderAndCollect(result.question); // your host
  ({ state, result } = await controller.step({ state, action }));
}
// result.status is now "done" | "invalid" | "cancelled"

Reflection face: describe / listChoices

For a form-style host that renders every field up front instead of one question at a time, describe returns the static shape of a method's inputs (required-ness, value type, which are dynamic, their dependencies), and listChoices enumerates the legal values for one dynamic parameter.

controller.describe({ method: "runAction" });
// { app: { required: true, dynamic: true }, action: { required: true, ... } }

await controller.listChoices({
  method: "runAction",
  parameter: "app",
  search: "sl",
});
// { data: [{ label: "Slack", value: "slack" }], nextCursor }

Stand-ins

When a plugin depends on something supplied elsewhere (a configured client, a test double), declare a typed stand-in with declareMethod / declareProperty (a single leaf) or declarePlugin (a whole module, with its export surface declared as leaf stand-ins). Dependents reference it for typing; at createSdk it is satisfied by whatever real plugin is registered under the same id, and an unsatisfied stand-in is a compile-time error (with a runtime backstop). You reference a stand-in by id (namespace/name, or a bare name), and the contract is provided as explicit type arguments (declareMethod<"fetch", Input, Output>({ id: "fetch" })), because the id must be a literal the dependency ledger can read. The binding is the id's last segment.

Namespaces

Plugin ids are name by default, or namespace/name when you set the optional namespace field. Namespacing lets two packages define a plugin with the same bare name without their ids colliding; the surface and imports stay bare-named, so consumers are unaffected.

const greet = defineMethod({
  name: "greet",
  namespace: "acme",
  run: () => "hi",
});
// id is "acme/greet"; sdk.greet() is still the call

Status

Pre-release. The public surface is being stabilized as part of an extraction from @zapier/zapier-sdk. Until a 1.0.0 release, expect breaking changes between minor versions.