@zapier/kitcore 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # @zapier/kitcore
 
+## 0.17.0
+
+### Minor Changes
+
+- 9cde1f6: **`getRegistry(sdk)` reads an SDK's registry without the SDK surfacing
+  anything**, and `createController` accepts any built SDK, so introspection costs
+  no `getRegistryPlugin` re-export. Re-export it anyway if you want
+  `sdk.getRegistry()` for your own callers; both return the same result.
+
+  Every accessor reads one registry: the free `getRegistry(sdk)`, a re-exported
+  `getRegistry()`, and the one a legacy-bridged SDK surfaces all return the same
+  memoized object. It is memoized per SDK and per package filter, and every reader
+  shares it, so `functions`, `categories`, and each category's own `functions` are
+  frozen. Copy before sorting or splicing. The memo lives on the SDK's context, so a process holding two
+  copies of kitcore, one bundled into a head and one loaded directly, shares it
+  and invalidates it once. A `createPluginStack()` build has no kitcore context and so no
+  memo: there the call forwards to the SDK's own `getRegistry()` and hands back a
+  fresh, mutable result each time.
+
+  **A property that declares `dynamicMembers` must have an object value when the
+  SDK is built.** `createSdk` throws otherwise, naming the property. The registry
+  reports a member like `apps.{appKey}` only while its root is a live object, and
+  that answer is memoized, so a root arriving later would leave the registry
+  reporting whatever was true when something first read it. Build the root in
+  `setup` and return it from `get`.
+
+  **`defineOverride(method, { ... })` patches how a surface presents a method.**
+  Pass the method itself, or a `declareMethod` stand-in when you want to patch one
+  without importing it, so no id is respelled and a rename cannot leave a silent
+  no-op behind. `namespace` names the override rather than the target, so two
+  surfaces can patch the same method in one graph. `defineMethodOverride({ target })`
+  still works and warns.
+
+  **An override patches presentation only.** Its config takes
+  `OverridableMetaFields`: `description`, `categories`, `itemType`, `returnType`,
+  `packages`, `experimental`, `deprecation`, and `supportsJsonOutput`. Anything
+  else throws, including for JavaScript callers the type does not reach. An
+  override changes how a surface describes a method, never what it does. A
+  method's declared type is fixed at `defineMethod` and nothing re-checks it
+  afterwards, so patching output validation, a host's confirmation prompt, or
+  which input a caller can pass would let a call fail against a contract its own
+  return type says it satisfies. That rules out `outputSchema`, `confirm`, and
+  `aliases`, and `type` too, because the registry derives `confirm` from it.
+
+  **Provide a declared method or property by reference.**
+  `defineProperty(ref, { value })` and `defineMethod(ref, { run })` take a
+  `declareProperty` / `declareMethod` stand-in instead of a config that respells
+  its `name` and `namespace`, so no id string is repeated and `value` and `run`
+  are typed against the declaration. It is also how a graph supplies framework
+  options as ordinary properties rather than through `createSdk`'s `configuration`
+  channel. The method form covers raw output only.
+
+  **`requireParameters` accepts an absolute path**, which says exactly which value
+  a resolver means. A bare name is convenient and can go wrong: it resolves in the
+  resolver's own container first, then the root, so when both hold the name the
+  container wins and there is no way to say otherwise. An array
+  (`[["nested", "owner"]]`) is a path from the root, so it names one place. It also
+  reaches a field inside another parameter, which no bare name can address. A
+  dotted string is one key, not a path.
+
+  **A raw method's `outputSchema` is enforced.** Raw has no envelope, so the schema
+  is matched against the whole return, and a method that meant to be
+  `output: "item"` and returns `{ data }` fails with an error saying so. It
+  validates without reshaping: the caller gets the original object back, extras and
+  all. **A raw method carrying a schema for projection only needs
+  `skipOutputValidation: true`.**
+
+  **A caller can skip output validation for one call** by passing
+  `skipOutputDataValidation: true` alongside an item or list method's input. An
+  author's `skipOutputValidation` wins, so a caller can only ever subtract. Raw
+  methods do not take it: their call object is entirely the author's, so the key
+  there is ordinary input.
+
+  **A call runs through BOTH schemas.** The framework's own parameters (`cursor`,
+  `pageSize`, `maxItems`, `skipOutputDataValidation`) are held to a minimal floor,
+  whatever a method declares and even when it declares no `inputSchema` at all.
+  The floor rejects only what the machinery cannot act on: `pageSize` at least 1,
+  because a page loop asking for zero items does not terminate, `maxItems` at
+  least 0, and `cursor` any string.
+
+  The method's own `inputSchema` then sees the whole call, so a constraint it
+  declares on one of those parameters still applies. Write
+  `pageSize: z.number().max(100)` and callers get your cap on top of the floor.
+  Nothing reads your schema's shape to work this out, so a `.transform()` or
+  `.refine()` wrapper cannot hide a declaration.
+
+  A `strict()` schema is the exception, since it cannot ignore a key it never
+  declared. When it rejects a framework parameter by name, that parameter is
+  removed and the parse runs again, so the method sees exactly the input it
+  described and the error names only the caller's own mistakes.
+
+  On the way to `run`, the framework's validated value wins for the parameters it
+  owns, so a caller asking for `pageSize: 5` gets 5. A list `run` receives the
+  `cursor` and `pageSize` of the page it must fetch. `maxItems` and the output
+  skip stop at the framework, which is the only thing that can act on them. The
+  types say the same: `Parameters<typeof method.run>[0]["input"]` carries the page
+  controls and nothing else.
+
+  **`meta.outputDataValidation` reports what the framework did**, typed
+  `OutputDataValidationReport`:
+
+  ```ts
+  | { skipped: true }
+  | { skipped: false; droppedPaths: null }
+  | { skipped: false; droppedPaths: string[]; instruction: string }
+  ```
+
+  `skipped` says whether the framework parsed, never that the data is unchecked.
+  `droppedPaths: null` means nothing was dropped, and `instruction` rides only the
+  arm where it is actionable. Reading `droppedPaths` requires narrowing on
+  `skipped` first. A report appears only when there is something to say: a caller's
+  skip that changed something, or paths dropped with the
+  `includeOutputValidationDroppedPaths` core option on.
+
+  The shape and the instruction wording match the connectors SDK, so a consumer
+  moving between them reads one report.
+
+  `meta.outputValidation` is deprecated in favour of it. It is still written, with
+  the same `{ droppedPaths }` shape and the same emission rule, and it will be
+  removed in a later release.
+
+  `StandInId` and `SdkContextCarrier` are exported so a package building on
+  kitcore can emit declarations that name them. Nothing asks you to write either
+  one yourself.
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -350,21 +350,23 @@ 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.
+`getRegistry(sdk)` 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. It needs nothing on the SDK itself.
 
 ```ts
-import { getRegistryPlugin } from "@zapier/kitcore";
+import { getRegistry } from "@zapier/kitcore";
 
-const sdk = createSdk(
-  definePlugin({ name: "api", exports: [greet, getRegistryPlugin] }),
-);
+const sdk = createSdk(definePlugin({ name: "api", exports: [greet] }));
 
-const registry = sdk.getRegistry();
+const registry = getRegistry(sdk);
 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`.
+Re-export the built-in `getRegistryPlugin` if you also want a `getRegistry()` method on the SDK surface for your own callers. It is a thin shim over the same result, so the two agree. Ids are scoped to a graph, so separate SDKs in one process can each register it; what cannot work is one graph pulling in two copies of kitcore, whose built-ins would then collide on the shared `kitcore/getRegistry` id. Introspection does not depend on the re-export either way.
+
+The result is memoized per SDK and per package filter, and `addPlugin` drops it, so a registry read still reflects anything added after the build. Because every reader shares that one object, its `functions` and `categories` arrays are frozen: copy before sorting or filtering in place.
+
+That holds for an SDK with a kitcore context, which is anything `createSdk` built. An SDK without one, meaning a `createPluginStack()` build, has no memo to share: `getRegistry(sdk)` forwards to the SDK's own `getRegistry()` and hands back whatever it builds, fresh and mutable on every call.
 
 ## Resolving inputs: controllers