@zapier/kitcore 0.11.0 → 0.13.0

package/dist/index.mjs

@@ -76,6 +76,15 @@ function isPositional(schema) {
   }
   return false;
 }
+function getNegatable(schema) {
+  const negatable = schema.meta?.()?.negatable;
+  if (negatable === true) return true;
+  if (typeof negatable === "string" && negatable.length > 0) return negatable;
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodDefault) {
+    return getNegatable(schema._zod.def.innerType);
+  }
+  return void 0;
+}
 function openEnum(values, description) {
   return z.union([z.enum(values), z.string()]).describe(description);
 }
@@ -924,7 +933,8 @@ function isSdkPage(value) {
 }
 function createPageFunction(coreFn, {
   sdk,
-  adaptPage
+  adaptPage,
+  finalizePage
 }) {
   const functionName = coreFn.name + "Page";
   const namedFunctions = {
@@ -937,7 +947,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,
@@ -956,9 +966,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) {
@@ -1484,6 +1499,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,
@@ -1590,6 +1606,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 {
@@ -1635,6 +1674,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 {
@@ -1936,6 +1980,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
@@ -1999,6 +2134,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();
@@ -2013,28 +2151,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);
@@ -2085,6 +2284,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({
@@ -2408,6 +2615,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",
@@ -2460,6 +2668,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),
@@ -2470,11 +2688,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),
         {
@@ -4190,7 +4412,9 @@ export {
   createSdk,
   createValidator,
   dangerousContextPlugin,
+  declareDefault,
   declareMethod,
+  declareOptionalMethod,
   declareOptionalProperty,
   declarePlugin,
   declareProperty,
@@ -4212,6 +4436,7 @@ export {
   getCurrentDepth,
   getCurrentScope,
   getFieldDescriptions,
+  getNegatable,
   getOutputSchema,
   getRegistryPlugin,
   getSchemaDescription,