@zapier/kitcore 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @zapier/kitcore
 
+## 0.5.1
+
+### Patch Changes
+
+- c398f14: A caller-provided parameter is now used exactly as given: `controller.resolve()` and `controller.start()` settle seeded input up front, so the resolution walk no longer descends into provided objects or arrays and only asks for parameters the caller left out.
+
+## 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

package/README.md

@@ -40,10 +40,11 @@ sdk.greet({ name: "Ada" }); // "Hi Ada"
 
 ## Plugins are modules
 
-There are three kinds of plugin, and an SDK is just a materialized plugin:
+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.
@@ -211,15 +212,19 @@ const fetchMethod = defineMethod({
 sdk.fetch("https://example.com", { method: "GET" });
 ```
 
-## Middleware
+## Hooks: wrap and observe
 
-An aggregate can wrap the methods it imports. A `middleware` 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.
+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
-const auth = definePlugin({
+import { defineHook } from "@zapier/kitcore";
+
+const auth = defineHook({
   name: "auth",
   imports: [transport, credentials],
-  middleware: {
+  wrap: {
     transport: ({ imports, next, input }) =>
       next({
         ...input,
@@ -228,34 +233,55 @@ const auth = definePlugin({
   },
 });
 
-const retry = definePlugin({
+const retry = defineHook({
   name: "retry",
   imports: [transport, auth], // import auth so retry nests around it
-  middleware: { transport: ({ next, input }) => withRetry(() => next(input)) },
+  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.
 
-### The context escape hatch (avoid)
+### Configuration
 
-There is a built-in `dangerousContextPlugin` that hands you the SDK's raw internal context (the live plugin graph plus legacy compatibility fields):
+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 { dangerousContextPlugin } from "@zapier/kitcore";
+import { declareOptionalProperty } from "@zapier/kitcore";
 
-const whoami = defineMethod({
-  name: "whoami",
-  imports: [dangerousContextPlugin],
-  run: ({ imports }) => Object.keys(imports.context.plugins),
+const configRef = declareOptionalProperty<"config", { pageSize?: number }>({
+  id: "config",
+});
+
+const listThings = defineMethod({
+  name: "listThings",
+  imports: [configRef],
+  run: ({ imports }) => api.list({ pageSize: imports.config?.pageSize ?? 10 }),
 });
-```
 
-**Steer clear of it.** The context shape is an internal implementation detail and may change without notice, so anything built on it is fragile. Import the specific plugins you need instead, and use `getRegistryPlugin` (below) for surface introspection. The `dangerous` prefix is there to make the risk loud at every import site; it exists mainly so a not-yet-migrated plugin can reach legacy state during a transition.
+const sdk = createSdk(listThings, {
+  configuration: { config: { pageSize: 50 } },
+});
+```
 
 ## Extending a built SDK
 
@@ -268,6 +294,24 @@ 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.