@zapier/kitcore 0.0.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# @zapier/kitcore
+
+## 0.5.0
+
+### Minor Changes
+
+- 5f5f028: The module model is complete; the legacy function-plugin bridge is deprecated.
+
+  New:
+  - `createSdk(root, { configuration })` injects immutable values by plugin id
+    at build time (your SDK's options, framework options). A `declareProperty`
+    or `declareOptionalProperty` (new) stand-in with a matching id receives the
+    value as a normal import.
+  - The `kitcore/coreOptions` configuration entry now accepts a
+    `logDeprecation` handler, called on every invocation of a deprecated
+    method. The default logs a warning once per process.
+  - `defineHook`, a new plugin kind that attaches behavior to methods:
+    `observe` runs `onMethodStart` / `onMethodEnd` observers over every method
+    call, and `wrap` is targeted, contract-preserving middleware over a direct
+    import (a `{ imports, input, state, next }` bag).
+  - Every plugin can declare `dispose` beside `setup`. `disposeSdk(sdk,
+input?)` runs them in reverse build order — call it to release what your
+    plugins acquired (timers, listeners). Idempotent; failures aggregate into
+    `CoreDisposeError`.
+  - `resolvePlugin(sdk, ref)` reads a plugin binding off a built sdk, for
+    infrastructure code that can't declare `imports`.
+  - `PluginSurface<typeof plugin>` derives the surface a plugin contributes
+    (method callable, property value, or an aggregate's bindings), so you don't
+    hand-write provides types. The `PluginSummary` / `LeafSummary` ledger types
+    are exported alongside it, so a package that exports plugins can emit their
+    inferred descriptor types — completeness ledger included — in its
+    declarations.
+  - Raw-output methods now get the full method boundary — input validation
+    branded through your `adaptError`, lifecycle hooks — while staying
+    synchronous.
+  - Object parameters resolve more naturally in interactive mode: an optional
+    object sits behind one entry question (declining skips its field fetch),
+    required fields come first, and the remaining optionals are offered as a
+    batch. A nested field's `requireParameters` can now name top-level
+    parameters. `collection` questions carry `container: "array" | "object"`;
+    hosts that render `message` + `actions` generically need no changes.
+
+  Breaking:
+  - `definePlugin`'s `middleware` map is removed. Declare a `defineHook` with
+    `wrap` instead.
+  - `listItems` is required on dynamic resolvers: a dynamic resolver IS a
+    candidate-lister. For a free-text field, use `type: "static"`.
+  - On `collection` questions, `count` and `min` are now optional (present on
+    array decisions only, absent on the new object gates). A host reading
+    `question.count` unconditionally must handle `undefined`.
+
+  Deprecated (runtime warnings now, removal in a later release):
+  `createPluginStack`, `createPluginMethod`, `createPaginatedPluginMethod`,
+  `createCorePlugin`, `fromFunctionPlugin`, `defineLegacyMerge`, and the
+  function form of `definePlugin`. Author with `defineMethod` /
+  `defineProperty` / `definePlugin({ ... })` and build with `createSdk`.
+
+  Fixed: an sdk built by one bundled copy of kitcore is now readable by another
+  copy's `getContext` / `resolvePlugin` (the context key moved to the global
+  symbol registry).
+
+## 0.4.0
+
+### Minor Changes
+
+- 5e2cf0d: Add the resolution controller: a sibling layer over a built SDK that completes a method's partial input into a fully validated one, interacting with a host only when needed. `createController(sdk)` exposes a wizard face (`resolve` / `start` / `step` over a serializable protocol) and a serializable reflection face (`listMethods` / `getMethod` / `listChoices`) that projects the registry to plain JSON (JSON Schema types, positional, output) without leaking zod. Adds the `defineResolver` authoring API and the signal hierarchy (`CoreSignal`, `CoreCancelledSignal`, `isCoreSignal`).
+
+## 0.3.0
+
+### Minor Changes
+
+- f5466d7: Publish kitcore publicly as `@zapier/kitcore`.
+
+  The package was previously private and internal-only. It is now published under the `@zapier` scope. It remains bundled into `@zapier/zapier-sdk` (unchanged); this additionally makes it available as a standalone package.
+
+## 0.2.0
+
+### Minor Changes
+
+- b8ff1dd: Refactor the SDKs onto kitcore's new internal plugin model.
+
+  kitcore (an internal building block) gained a new plugin model, and the SDKs were rebuilt on it behind a compatibility bridge, so existing behavior is unchanged. The only changes to the published packages' surface:
+  - Removed the deprecated `sdk.addPlugin(...)` chain method (and the `WithAddPlugin` type / chain-style no-arg `createSdk()` doorway). Extend a built SDK with the top-level `addPlugin(sdk, plugin)` instead.
+  - `@zapier/zapier-sdk` now re-exports the plugin-authoring helpers (`createSdk`, `defineMethod` / `definePlugin` / `declareMethod` / etc., `selectExports`, `addPlugin`). Note `createSdk` reuses the old doorway's name but now takes a root plugin, so a stale no-arg `createSdk()` call is a compile error rather than silent misbehavior.
+
+## 0.1.0
+
+### Minor Changes
+
+- 571f90d: Add zapier-sdk-package-operation header to identify the caller operation
+
+## 0.0.1
+
+### Patch Changes
+
+- da80c77: Fix paginated list results silently truncating to page 1 when the same result is consumed twice (iterating pages then `.items()`, `.items()` then pages, or iterating either one twice). Pages and items are now two views over one page stream, so consuming either drains the other: the second view yields nothing instead of silently replaying page 1. A paginated result is consumed once; call the method again for a fresh result. Awaiting the result to read just the first page is unaffected: it is a repeatable peek that does not start the stream, so awaiting and then iterating still works.

package/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Zapier, Inc.
+The Zapier SDK is part of Zapier's services.  By downloading, installing, accessing, or using any part of the Zapier SDK you agree to the Zapier Terms of Service, which can be found at: https://zapier.com/tos, or such other agreement between you and Zapier governing Zapier services (as applicable).  If you do not agree to the Zapier Terms of Service (or do not have another governing agreement in place with Zapier), you may not download, install, access, or use the Zapier SDK.

package/README.md

@@ -1,5 +1,429 @@
 # @zapier/kitcore
 
-Placeholder release that reserves the `@zapier/kitcore` name on the registry with public access.
+A TypeScript framework for building plugin-driven SDKs.
 
-Install the latest published version for actual usage.
+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
+
+```bash
+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.
+
+```ts
+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](#hooks-wrap-and-observe)).
+- **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.
+
+```ts
+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.
+
+```ts
+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).
+
+```ts
+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`.
+
+```ts
+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`.
+
+```ts
+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.
+
+```ts
+// 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:
+
+```ts
+// raw (default): the surface is whatever run returns
+const transport = defineMethod({
+  name: "transport",
+  run: ({ input }) => fetch(input.url),
+});
+
+// item: run returns the value; the framework wraps it in { data }
+const getApp = defineMethod({ name: "getApp", output: "item", run: () => 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 }`.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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).
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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`](https://www.npmjs.com/package/@zapier/zapier-sdk). Until a `1.0.0` release, expect breaking changes between minor versions.