@zapier/kitcore 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @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

package/README.md

@@ -443,9 +443,36 @@ await controller.listChoices({
 // { data: [{ label: "Slack", value: "slack" }], nextCursor }
 ```
 
-## Stand-ins
+## Plugin references
 
-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.
+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.
+
+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
 

package/dist/index.cjs

@@ -49,7 +49,9 @@ __export(index_exports, {
   createSdk: () => createSdk,
   createValidator: () => createValidator,
   dangerousContextPlugin: () => dangerousContextPlugin,
+  declareDefault: () => declareDefault,
   declareMethod: () => declareMethod,
+  declareOptionalMethod: () => declareOptionalMethod,
   declareOptionalProperty: () => declareOptionalProperty,
   declarePlugin: () => declarePlugin,
   declareProperty: () => declareProperty,
@@ -1024,7 +1026,8 @@ function isSdkPage(value) {
 }
 function createPageFunction(coreFn, {
   sdk,
-  adaptPage
+  adaptPage,
+  finalizePage
 }) {
   const functionName = coreFn.name + "Page";
   const namedFunctions = {
@@ -1037,7 +1040,7 @@ function createPageFunction(coreFn, {
             `${functionName}: paginated result must be exactly { data: TItem[], nextCursor? } (produced by the handler or its \`adaptPage\`); got keys [${page && typeof page === "object" ? Object.keys(page).join(", ") : typeof page}]. If the handler returns a raw shape, set \`adaptPage\` to translate it; if \`adaptPage\` already runs, it must return only \`data\`/\`nextCursor\`.`
           );
         }
-        return page;
+        return finalizePage ? finalizePage(page) : page;
       } catch (error) {
         throw normalizeError(
           error,
@@ -1056,9 +1059,14 @@ function createPaginatedFunction(coreFn, options) {
     defaultPageSize,
     adaptPage,
     annotator,
+    finalizePage,
     getDeprecation
   } = options;
-  const pageFunction = createPageFunction(coreFn, { sdk, adaptPage });
+  const pageFunction = createPageFunction(coreFn, {
+    sdk,
+    adaptPage,
+    finalizePage
+  });
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: function(callOptions) {
@@ -1584,6 +1592,7 @@ function defineMethod(config) {
     importBindings: deps.bindings,
     inputSchema: config.inputSchema,
     skipInputValidation: config.skipInputValidation,
+    skipOutputValidation: config.skipOutputValidation,
     meta: collectLeafMeta(config),
     resolvers: config.resolvers,
     formatter: config.formatter,
@@ -1690,6 +1699,29 @@ function declareMethod(config) {
     }
   };
 }
+function declareOptionalMethod(config) {
+  const { name, namespace } = parseId(config.id);
+  const id = makeId(name, namespace);
+  return {
+    pluginType: "method",
+    name,
+    namespace,
+    id,
+    standIn: true,
+    optional: true,
+    imports: [],
+    importBindings: [],
+    run: () => {
+      throw new Error(
+        `Plugin "${id}" is an optional stand-in (declareOptionalMethod) with no implementation. Its binding is \`undefined\` unless a real plugin is registered under this id.`
+      );
+    }
+    // Requires nothing (phantom carrier `<never, never>`): a consumer that
+    // imports it still passes `createSdk`'s completeness check unprovided. The
+    // `optional: true` literal drives `PluginSurface` to type the binding
+    // `| undefined`.
+  };
+}
 function defineProperty(config) {
   const deps = normalizeImports(config.imports);
   return {
@@ -1735,6 +1767,11 @@ function declareOptionalProperty(config) {
     // import binding is still typed `TValue | undefined` from the descriptor.
   };
 }
+function declareDefault({
+  plugin
+}) {
+  return { ...plugin, defaultSource: plugin };
+}
 function defineHook(config) {
   const deps = normalizeImports(config.imports);
   return {
@@ -2036,6 +2073,97 @@ var getRegistryPlugin = defineMethod({
   run: ({ imports, input }) => buildSurfaceRegistry(imports.context, input?.package)
 });
 
+// src/utils/output-policy.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function diffDroppedPaths(raw, parsed, prefix = "") {
+  const paths = [];
+  walkDroppedPaths(raw, parsed, prefix, paths);
+  return paths;
+}
+function walkDroppedPaths(raw, parsed, prefix, out) {
+  if (Array.isArray(raw) && Array.isArray(parsed)) {
+    const seen = /* @__PURE__ */ new Set();
+    const length = Math.min(raw.length, parsed.length);
+    for (let index = 0; index < length; index++) {
+      const elementPaths = [];
+      walkDroppedPaths(raw[index], parsed[index], `${prefix}[]`, elementPaths);
+      for (const path of elementPaths) {
+        if (seen.has(path)) continue;
+        seen.add(path);
+        out.push(path);
+      }
+    }
+    return;
+  }
+  if (isRecord(raw) && isRecord(parsed)) {
+    for (const key of Object.keys(raw)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (!(key in parsed)) {
+        out.push(path);
+        continue;
+      }
+      walkDroppedPaths(raw[key], parsed[key], path, out);
+    }
+    return;
+  }
+}
+function parseOutput(schema, value, policy, locator) {
+  const result = schema.safeParse(value);
+  if (result.success) return result.data;
+  const issues = result.error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "data";
+    return `${path}: ${issue.message}`;
+  });
+  const subject = policy.methodName ? ` for "${policy.methodName}"` : "";
+  const at = locator ? ` at ${locator}` : "";
+  throw createCoreError(
+    {
+      code: CoreErrorCode.Validation,
+      message: `Output validation failed${subject}${at}:
+  ${issues.join("\n  ")}
+
+The response does not match the method's \`outputSchema\`. Correct the schema, or set \`skipOutputValidation: true\` on the method to pass the response through unvalidated.`,
+      details: { zodErrors: result.error.issues, output: value }
+    },
+    policy.adaptError
+  );
+}
+function applyItemOutputPolicy(result, policy) {
+  const schema = policy.outputSchema;
+  if (!schema || policy.skipOutputValidation) return result;
+  if (!isRecord(result) || !("data" in result)) return result;
+  const data = parseOutput(schema, result.data, policy);
+  const next = { ...result, data };
+  if (policy.includeOutputValidationDroppedPaths) {
+    const droppedPaths = diffDroppedPaths(result.data, data);
+    if (droppedPaths.length > 0) {
+      next.meta = withOutputValidation(result.meta, droppedPaths);
+    }
+  }
+  return next;
+}
+function withOutputValidation(existing, droppedPaths) {
+  const base = isRecord(existing) ? existing : {};
+  return { ...base, outputValidation: { droppedPaths } };
+}
+function applyListOutputPolicy(page, policy) {
+  const schema = policy.outputSchema;
+  if (!schema || policy.skipOutputValidation) return page;
+  const data = page.data.map(
+    (item, index) => parseOutput(schema, item, policy, `data[${index}]`)
+  );
+  const next = { ...page, data };
+  if (policy.includeOutputValidationDroppedPaths) {
+    const droppedPaths = diffDroppedPaths(page.data, data);
+    if (droppedPaths.length > 0) {
+      next.meta = { ...page.meta, outputValidation: { droppedPaths } };
+    }
+  }
+  return next;
+}
+
 // src/model/materialize.ts
 var FRAMEWORK_CONFIGURATION_IDS = /* @__PURE__ */ new Set([
   CORE_OPTIONS_ID
@@ -2099,6 +2227,9 @@ function edgesOf(plugin) {
 function isStandIn(plugin) {
   return (plugin.pluginType === "method" || plugin.pluginType === "property" || plugin.pluginType === "aggregate") && plugin.standIn === true;
 }
+function isDefault(plugin) {
+  return (plugin.pluginType === "method" || plugin.pluginType === "property") && plugin.defaultSource !== void 0;
+}
 function topoOrder(descriptors) {
   const order = [];
   const visited = /* @__PURE__ */ new Set();
@@ -2113,28 +2244,89 @@ function topoOrder(descriptors) {
   return order;
 }
 function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configuration) {
+  const rank = (plugin) => isStandIn(plugin) ? 0 : isDefault(plugin) ? 1 : 2;
+  const allNodes = [];
+  const seen = /* @__PURE__ */ new Set();
+  const collect = (plugin) => {
+    if (materialized.has(plugin.id) || seen.has(plugin)) return;
+    seen.add(plugin);
+    allNodes.push(plugin);
+    for (const edge of edgesOf(plugin)) collect(edge);
+  };
+  collect(root);
+  const childrenOf = /* @__PURE__ */ new Map();
+  const candidatesById = /* @__PURE__ */ new Map();
+  for (const node of allNodes) {
+    childrenOf.set(
+      node,
+      edgesOf(node).filter((edge) => seen.has(edge))
+    );
+    const candidates = candidatesById.get(node.id);
+    if (candidates) candidates.push(node);
+    else candidatesById.set(node.id, [node]);
+  }
+  const live = new Set(allNodes);
+  for (; ; ) {
+    const reachable = /* @__PURE__ */ new Set();
+    if (live.has(root)) reachable.add(root);
+    const queue = reachable.has(root) ? [root] : [];
+    while (queue.length) {
+      const node = queue.pop();
+      for (const child of childrenOf.get(node) ?? []) {
+        if (reachable.has(child)) continue;
+        reachable.add(child);
+        if (live.has(child)) queue.push(child);
+      }
+    }
+    let changed = false;
+    for (const node of live) {
+      if (!reachable.has(node)) {
+        live.delete(node);
+        changed = true;
+      }
+    }
+    for (const candidates of candidatesById.values()) {
+      let maxRank = -1;
+      for (const candidate of candidates) {
+        if (live.has(candidate)) maxRank = Math.max(maxRank, rank(candidate));
+      }
+      if (maxRank < 0) continue;
+      for (const candidate of candidates) {
+        if (live.has(candidate) && rank(candidate) < maxRank) {
+          live.delete(candidate);
+          changed = true;
+        }
+      }
+    }
+    if (!changed) break;
+  }
   const byId = /* @__PURE__ */ new Map();
-  const visit = (plugin) => {
-    if (materialized.has(plugin.id)) return;
-    const existing = byId.get(plugin.id);
-    if (existing === plugin) return;
-    if (existing) {
-      const bothReal = !isStandIn(existing) && !isStandIn(plugin);
-      if (bothReal) {
+  const conflictedDefaults = /* @__PURE__ */ new Set();
+  const isOptional = (plugin) => "optional" in plugin && plugin.optional === true;
+  for (const [id, candidates] of candidatesById) {
+    const liveCandidates = candidates.filter(
+      (candidate) => live.has(candidate)
+    );
+    const winner = liveCandidates.find((candidate) => !isOptional(candidate)) ?? liveCandidates[0];
+    if (!winner) continue;
+    if (liveCandidates.length > 1) {
+      const winnerRank = rank(winner);
+      if (winnerRank === 2) {
         throw new Error(
-          `createSdk: duplicate plugin id "${plugin.id}". Two different plugins registered under the same id.`
+          `createSdk: duplicate plugin id "${id}". Two different plugins registered under the same id.`
         );
       }
-      if (isStandIn(existing) && !isStandIn(plugin)) {
-        byId.set(plugin.id, plugin);
-        for (const edge of edgesOf(plugin)) visit(edge);
+      if (winnerRank === 1) {
+        const sources = new Set(
+          liveCandidates.map(
+            (candidate) => candidate.defaultSource
+          )
+        );
+        if (sources.size > 1) conflictedDefaults.add(id);
       }
-      return;
     }
-    byId.set(plugin.id, plugin);
-    for (const edge of edgesOf(plugin)) visit(edge);
-  };
-  visit(root);
+    byId.set(id, winner);
+  }
   if (configuration) {
     for (const [id, value] of Object.entries(configuration)) {
       const existing = byId.get(id);
@@ -2185,6 +2377,14 @@ function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configur
       );
     }
   }
+  for (const id of conflictedDefaults) {
+    const winner = byId.get(id);
+    if (winner && isDefault(winner)) {
+      throw new Error(
+        `createSdk: conflicting defaults for "${id}". Two different plugins were declared as defaults for the same id and nothing else provides it. Register an explicit (non-default) plugin for this id to choose the winner, or give the implementations distinct ids if they are meant to coexist.`
+      );
+    }
+  }
   return byId;
 }
 function bindValue({
@@ -2508,6 +2708,7 @@ function buildMethodEntries(descriptors, context, states) {
   const plugins = context.plugins;
   for (const [id, descriptor] of descriptors) {
     if (descriptor.pluginType !== "method") continue;
+    if (isStandIn(descriptor)) continue;
     const out = normalizeOutput(descriptor.output);
     const entry = {
       pluginType: "method",
@@ -2560,6 +2761,16 @@ function buildMethodEntries(descriptors, context, states) {
     const sdk = { context };
     const methodAnnotator = descriptor.annotator;
     const boundAnnotator = methodAnnotator ? (input) => methodAnnotator({ input }) : void 0;
+    const outputPolicy = () => {
+      const core = resolveCoreOptions(context);
+      return {
+        outputSchema: descriptor.meta?.outputSchema,
+        skipOutputValidation: descriptor.skipOutputValidation,
+        includeOutputValidationDroppedPaths: core?.includeOutputValidationDroppedPaths,
+        methodName: descriptor.name,
+        adaptError: core?.adaptError
+      };
+    };
     if (out.type === "list") {
       entry.value = createPaginatedFunction(
         fold(callRun),
@@ -2570,11 +2781,15 @@ function buildMethodEntries(descriptors, context, states) {
           defaultPageSize: out.defaultPageSize,
           adaptPage: out.adaptPage,
           annotator: boundAnnotator,
+          // Validate + strip each item against the item `outputSchema`
+          // (item mode's sibling); dropped paths surface as `[].x` in the page's
+          // `meta`, unioned across items.
+          finalizePage: (page) => applyListOutputPolicy(page, outputPolicy()),
           getDeprecation: () => entry.meta?.deprecation
         }
       );
     } else if (out.type === "item") {
-      const itemCore = async (input, ctx) => callRun(input, ctx);
+      const itemCore = async (input, ctx) => applyItemOutputPolicy(await callRun(input, ctx), outputPolicy());
       entry.value = createFunction(
         fold(itemCore),
         {
@@ -4291,7 +4506,9 @@ function createCorePlugin(options) {
   createSdk,
   createValidator,
   dangerousContextPlugin,
+  declareDefault,
   declareMethod,
+  declareOptionalMethod,
   declareOptionalProperty,
   declarePlugin,
   declareProperty,