@zapier/kitcore 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @zapier/kitcore
 
+## 0.12.0
+
+### Minor Changes
+
+- 281513d: Added `declareDefault`, a helper that imports the capability a plugin provides and defaults to that plugin when nothing else provides its id. Unlike `declareMethod` / `declareProperty`, it carries a real plugin, so its id, type, and kind come from the plugin (one kind-agnostic helper, no method/property split). At materialization an explicit provider of the same id preempts the default with no duplicate-id error, a lone default is used, and two different defaults for one id error only when nothing else provides it.
+
+  Added `declareOptionalMethod`, the method twin of `declareOptionalProperty`: an optional stand-in for a method registered elsewhere. When nothing provides the id it is not a missing dependency; the import binds `undefined` (typed `callable | undefined`), so a consumer can reference a foreign method that may or may not be present and call it as `imports.method?.(...)`.
+
+- 87e634f: A method's `outputSchema` is now enforced at runtime instead of being documentation-only: the framework validates and strips the method's output against it, an `item` method's `{ data }` envelope as a whole and a `list` method's page element by element. A failure names the method and routes through the head's `adaptError`.
+  - `skipOutputValidation` on `defineMethod` opts a method out, the output-side partner of `skipInputValidation`. Set it when a schema is meant for projection only (registry, CLI, MCP, docs) and must not shape the response.
+  - The `includeOutputValidationDroppedPaths` core option reports what the strip removed, as `meta.outputValidation.droppedPaths`. Off by default; turn it on while reconciling a schema against what an API actually returns, so an over-narrow schema surfaces as data loss instead of looking like the API stopped returning a field.
+  - `ResponseMeta` types that sidecar. An `item` method's declared return is now `{ data, meta? }` and `SdkPage` gains the same optional `meta`, so a report reads the same whichever mode produced it. Both stay framework-set: a handler or `adaptPage` returns only `data` / `nextCursor`.
+
+  Existing methods that declare an `outputSchema` need to either confirm it matches what the API returns or set `skipOutputValidation: true`, since a schema that was previously ignored now shapes the response.
+
+## 0.11.0
+
+### Minor Changes
+
+- 60892be: Added an explicit per-call annotation channel for attaching and reading per-invocation metadata:
+  - A method's `run` bag now includes the live `callContext` plus an `annotate(metadata)` function for recording per-invocation metadata onto the call's annotation bag.
+  - The `onMethodStart` / `onMethodEnd` hook context now carries `callId`, the call's `annotations`, and a `callOrigin` field (`"surface"` | `"internal"`), so observers can read a call's correlation id, annotations, and origin directly.
+  - `CallContext` gains a `callOrigin` field (`"surface"` | `"internal"`) that marks framework-internal calls, letting observers distinguish user calls from framework machinery (e.g. to keep framework calls out of telemetry). It is inherited by child calls, so a delegated subtree shares its root's origin.
+  - `defineHook` gains an optional `annotator` for deriving annotations from a call's input before `onMethodStart`. Multiple plugins' annotators compose (merged right-additively into the call's annotation bag), so annotation is contributed through the plugin graph rather than a single handler.
+  - `defineMethod` gains an optional pre-run `annotator` whose result merges into the call's annotations before `run`.
+  - Exported the `CallContext`, `Annotations`, and `CallOrigin` types, plus the `MethodAnnotator`, `HookAnnotator`, and `ComposedAnnotator` annotator function types.
+
 ## 0.10.1
 
 ### Patch Changes

package/README.md

@@ -44,7 +44,7 @@ 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)).
+- **Hook** (`defineHook`) — a leaf contributing cross-cutting behavior (see [Hooks](#hooks-wrap-observe-and-annotate)).
 - **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.
@@ -120,6 +120,26 @@ 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.
 
+## Per-call context and annotations
+
+Every method `run` bag includes a live `callContext` with the invocation's `callId`, `depth`, `callOrigin`, and `annotations`. Each method invocation gets its own annotation bag; a delegated child shares its root's call ID and origin but starts with empty annotations.
+
+Use the run bag's `annotate(fields)` helper for metadata learned during execution. For metadata available from raw input, a method can declare a synchronous `annotator`; it runs before validation, `onMethodStart`, and `run`, so its `input` is `unknown` and must be narrowed before fields are read.
+
+```ts
+const runJob = defineMethod({
+  name: "runJob",
+  annotator: () => ({ operationType: "write" }),
+  run: async ({ input, callContext, annotate }) => {
+    const worker = await selectWorker(input);
+    annotate({ worker });
+    return executeJob(input, callContext.annotations);
+  },
+});
+```
+
+Both forms merge into the same bag. `annotator` supplies fields before the method starts; `annotate` adds fields as the method runs.
+
 ## 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`.
@@ -217,9 +237,9 @@ const fetchMethod = defineMethod({
 sdk.fetch("https://example.com", { method: "GET" });
 ```
 
-## Hooks: wrap and observe
+## Hooks: wrap, observe, and annotate
 
-Cross-cutting behavior lives in a **hook** (`defineHook`), a fourth kind of leaf with two faces.
+Cross-cutting behavior lives in a **hook** (`defineHook`), a fourth kind of leaf with three 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.
 
@@ -260,6 +280,17 @@ const telemetry = defineHook({
 });
 ```
 
+`annotator` adds cross-cutting annotations before `onMethodStart`. It is a synchronous mapper over `{ methodName, input, state }`; like method annotators, it receives raw pre-validation input. Multiple hook annotators compose in graph order, later fields win on collision, and the method's own annotator runs last. Each contributor is best-effort, so a thrown annotation error never breaks the method or suppresses other contributors.
+
+```ts
+const classifyOperations = defineHook({
+  name: "classifyOperations",
+  annotator: ({ methodName }) => ({ methodCategory: classify(methodName) }),
+});
+```
+
+Hook annotators run only for outermost surface-origin calls. They are suppressed for nested and internal-origin calls, and for methods called from an observer or another hook annotator. A method's own annotator still runs for every invocation, including those suppressed cases, so method behavior does not depend on how the method was reached.
+
 A hook joins the graph like any other plugin: import or export it from an aggregate.
 
 ## Dependency injection
@@ -412,9 +443,36 @@ await controller.listChoices({
 // { data: [{ label: "Slack", value: "slack" }], nextCursor }
 ```
 
-## Stand-ins
+## Plugin references
+
+A plugin _references_ a capability supplied elsewhere by its id, without providing it. Use `declareMethod` / `declareProperty` for a single leaf, or `declarePlugin` for a whole module (its export surface declared as leaf references). A reference binds, at `createSdk`, to whatever real plugin is registered under the same id. You reference by `id` (`namespace/name`, or a bare name), with the contract 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.
+
+Two flavors, by what happens when nothing provides the id:
+
+- **Required** (`declareMethod` / `declareProperty`): an unsatisfied reference is a **compile-time** error (with a runtime backstop). Use when the capability must be present.
+- **Optional** (`declareOptionalProperty` / `declareOptionalMethod`): binds `undefined` instead of failing, so the consumer handles absence in code (`{ ...DEFAULTS, ...imports.config }` for a value, `imports.track?.(...)` for a method). Use to reference a _foreign_ capability userland may or may not import, without claiming its slot.
+
+## Defaults
+
+When you _own_ a capability slot and can ship a working implementation, register it as a default with `declareDefault({ plugin })` rather than referencing it. A default is a real, single node in the graph, so it works out of the box, hooks and middleware can wrap it, and an explicit provider of the same id silently preempts it (that is the seam for userland or another plugin to replace it).
+
+```ts
+import { declareDefault } from "@zapier/kitcore";
+
+const httpPlugin = defineMethod({
+  name: "http",
+  // Ship a working default pipeline stage; userland can wrap or replace it.
+  imports: [declareDefault({ plugin: defaultAuthStagePlugin })],
+  run: ({ imports }) => imports.authStage(/* ... */),
+});
+```
+
+Default versus optional reference is an ownership question:
+
+- **Own the slot** → default. It is yours to provide, so provide the fallback.
+- **Don't own it** → optional reference. Point at it without claiming it.
 
-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.
+The collision rules follow from ownership: two plugins defaulting one id to _different_ implementations conflict (both claimed the slot), while two optional references to the same foreign id never conflict (neither did). So a default on an id you do not own is a latent conflict, triggered the moment a second plugin does the same.
 
 ## Namespaces