@zapier/kitcore 0.10.0 → 0.11.0

package/dist/index.mjs

@@ -168,13 +168,39 @@ function buildRegistry({
 }
 
 // src/utils/build-hooks.ts
+var isolated = /* @__PURE__ */ new WeakSet();
+function isolate(observer) {
+  if (!observer) return void 0;
+  if (isolated.has(observer)) return observer;
+  const wrapped = (ctx) => {
+    try {
+      observer(ctx);
+    } catch (error) {
+      console.error(
+        "[core] A method-lifecycle observer threw and was ignored. Observers are fire-and-forget and must not throw.",
+        error
+      );
+    }
+  };
+  isolated.add(wrapped);
+  return wrapped;
+}
 function composeVoid(existing, added) {
+  const wrappedExisting = isolate(existing);
+  const wrappedAdded = isolate(added);
+  if (!wrappedExisting) return wrappedAdded;
+  if (!wrappedAdded) return wrappedExisting;
+  const composed = (ctx) => {
+    wrappedExisting(ctx);
+    wrappedAdded(ctx);
+  };
+  isolated.add(composed);
+  return composed;
+}
+function composeAnnotators(existing, added) {
   if (!existing) return added;
   if (!added) return existing;
-  return (ctx) => {
-    existing(ctx);
-    added(ctx);
-  };
+  return (ctx) => ({ ...existing(ctx), ...added(ctx) });
 }
 function buildHooks(existing, added) {
   const result = {};
@@ -182,6 +208,8 @@ function buildHooks(existing, added) {
   if (start2) result.onMethodStart = start2;
   const end = composeVoid(existing.onMethodEnd, added.onMethodEnd);
   if (end) result.onMethodEnd = end;
+  const annotator = composeAnnotators(existing.annotator, added.annotator);
+  if (annotator) result.annotator = annotator;
   return result;
 }
 
@@ -656,11 +684,14 @@ function generateCallId() {
   }
   return null;
 }
-function rootCallContext() {
+function rootCallContext({
+  callOrigin = "surface"
+} = {}) {
   return {
     callId: generateCallId(),
     depth: 0,
     annotations: {},
+    callOrigin,
     [CALL_CONTEXT_BRAND]: true
   };
 }
@@ -669,6 +700,7 @@ function childCallContext(parent) {
     callId: parent.callId,
     depth: parent.depth + 1,
     annotations: {},
+    callOrigin: parent.callOrigin,
     [CALL_CONTEXT_BRAND]: true
   };
 }
@@ -694,6 +726,28 @@ var INTERNAL_CALL = Symbol("kitcore.internalCall");
 function resolveCallContext(secondArg) {
   return isCallContext(secondArg) ? secondArg : rootCallContext();
 }
+var hookAnnotatorReentrancy = 0;
+function applyAnnotations({
+  context,
+  methodName,
+  input,
+  hookAnnotator,
+  methodAnnotator
+}) {
+  if (hookAnnotator && !isInsideObserver() && context.depth === 0 && context.callOrigin !== "internal" && hookAnnotatorReentrancy === 0) {
+    hookAnnotatorReentrancy++;
+    try {
+      Object.assign(context.annotations, hookAnnotator({ methodName, input }));
+    } catch {
+    } finally {
+      hookAnnotatorReentrancy--;
+    }
+  }
+  try {
+    Object.assign(context.annotations, methodAnnotator?.(input));
+  } catch {
+  }
+}
 function signalDeprecation(context, methodName, getDeprecation) {
   if (isInsideObserver()) return;
   const deprecation = getDeprecation?.();
@@ -719,7 +773,7 @@ function normalizeError(error, adaptError) {
   );
 }
 function createFunction(coreFn, options) {
-  const { sdk, schema, name, getDeprecation } = options;
+  const { sdk, schema, name, annotator, getDeprecation } = options;
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: async function(callOptions) {
@@ -733,14 +787,26 @@ function createFunction(coreFn, options) {
         const normalizedOptions = callOptions ?? {};
         const args = [normalizedOptions];
         const depth = Math.max(context.depth, getCurrentDepth());
-        const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const insideObserver = isInsideObserver();
+        const hooks = insideObserver ? void 0 : sdk.context.hooks;
         const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
-        hooks?.onMethodStart?.({
+        applyAnnotations({
+          context,
+          methodName: functionName,
+          input: normalizedOptions,
+          hookAnnotator: hooks?.annotator,
+          methodAnnotator: annotator
+        });
+        const hookBase = {
           methodName: functionName,
           args,
           isPaginated: false,
-          depth
-        });
+          depth,
+          callId: context.callId,
+          callOrigin: context.callOrigin,
+          annotations: context.annotations
+        };
+        hooks?.onMethodStart?.({ ...hookBase });
         try {
           let result;
           if (schema) {
@@ -762,20 +828,14 @@ function createFunction(coreFn, options) {
             result = await coreFn(normalizedOptions, context);
           }
           hooks?.onMethodEnd?.({
-            methodName: functionName,
-            args,
-            isPaginated: false,
-            depth,
+            ...hookBase,
             durationMs: Date.now() - startTime
           });
           return result;
         } catch (error) {
           const normalizedError = normalizeError(error, adaptError);
           hooks?.onMethodEnd?.({
-            methodName: functionName,
-            args,
-            isPaginated: false,
-            depth,
+            ...hookBase,
             durationMs: Date.now() - startTime,
             error: normalizedError
           });
@@ -787,7 +847,7 @@ function createFunction(coreFn, options) {
   return namedFunctions[functionName];
 }
 function createRawFunction(coreFn, options) {
-  const { sdk, name, schema, positional, getDeprecation } = options;
+  const { sdk, name, schema, positional, annotator, getDeprecation } = options;
   return function(rawInput) {
     const internal = arguments[1];
     const context = resolveCallContext(internal);
@@ -797,23 +857,32 @@ function createRawFunction(coreFn, options) {
     return runInMethodScope(() => {
       const startTime = Date.now();
       const depth = Math.max(context.depth, getCurrentDepth());
-      const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+      const insideObserver = isInsideObserver();
+      const hooks = insideObserver ? void 0 : sdk.context.hooks;
       const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
       const input = schema ? rawInput ?? {} : rawInput;
+      applyAnnotations({
+        context,
+        methodName: name,
+        input,
+        hookAnnotator: hooks?.annotator,
+        methodAnnotator: annotator
+      });
       const record = input;
       const args = positional ? positional.filter((key) => record?.[key] !== void 0).map((key) => record?.[key]) : [input];
-      hooks?.onMethodStart?.({
+      const hookBase = {
         methodName: name,
         args,
         isPaginated: false,
-        depth
-      });
+        depth,
+        callId: context.callId,
+        callOrigin: context.callOrigin,
+        annotations: context.annotations
+      };
+      hooks?.onMethodStart?.({ ...hookBase });
       const fireEnd = (error) => {
         hooks?.onMethodEnd?.({
-          methodName: name,
-          args,
-          isPaginated: false,
-          depth,
+          ...hookBase,
           durationMs: Date.now() - startTime,
           ...error ? { error } : {}
         });
@@ -880,7 +949,15 @@ function createPageFunction(coreFn, {
   return namedFunctions[functionName];
 }
 function createPaginatedFunction(coreFn, options) {
-  const { sdk, schema, name, defaultPageSize, adaptPage, getDeprecation } = options;
+  const {
+    sdk,
+    schema,
+    name,
+    defaultPageSize,
+    adaptPage,
+    annotator,
+    getDeprecation
+  } = options;
   const pageFunction = createPageFunction(coreFn, { sdk, adaptPage });
   const functionName = name || coreFn.name;
   const namedFunctions = {
@@ -895,14 +972,26 @@ function createPaginatedFunction(coreFn, options) {
         const normalizedOptions = callOptions ?? {};
         const args = [normalizedOptions];
         const depth = Math.max(context.depth, getCurrentDepth());
-        const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const insideObserver = isInsideObserver();
+        const hooks = insideObserver ? void 0 : sdk.context.hooks;
         const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
-        hooks?.onMethodStart?.({
+        applyAnnotations({
+          context,
+          methodName: functionName,
+          input: normalizedOptions,
+          hookAnnotator: hooks?.annotator,
+          methodAnnotator: annotator
+        });
+        const hookBase = {
           methodName: functionName,
           args,
           isPaginated: true,
-          depth
-        });
+          depth,
+          callId: context.callId,
+          callOrigin: context.callOrigin,
+          annotations: context.annotations
+        };
+        hooks?.onMethodStart?.({ ...hookBase });
         try {
           const validatedOptions = {
             ...normalizedOptions,
@@ -925,24 +1014,21 @@ function createPaginatedFunction(coreFn, options) {
             return result.value;
           });
           if (hooks?.onMethodEnd) {
-            firstPagePromise.then(() => {
-              hooks.onMethodEnd({
-                methodName: functionName,
-                args,
-                isPaginated: true,
-                depth,
-                durationMs: Date.now() - startTime
-              });
-            }).catch((error) => {
-              hooks.onMethodEnd({
-                methodName: functionName,
-                args,
-                isPaginated: true,
-                depth,
-                durationMs: Date.now() - startTime,
-                error: error instanceof Error ? error : new Error(String(error))
-              });
-            });
+            firstPagePromise.then(
+              () => {
+                hooks.onMethodEnd({
+                  ...hookBase,
+                  durationMs: Date.now() - startTime
+                });
+              },
+              (error) => {
+                hooks.onMethodEnd({
+                  ...hookBase,
+                  durationMs: Date.now() - startTime,
+                  error: error instanceof Error ? error : new Error(String(error))
+                });
+              }
+            );
           }
           const pageStream = async function* () {
             yield await firstPagePromise;
@@ -976,10 +1062,7 @@ function createPaginatedFunction(coreFn, options) {
         } catch (error) {
           const normalizedError = normalizeError(error, adaptError);
           hooks?.onMethodEnd?.({
-            methodName: functionName,
-            args,
-            isPaginated: true,
-            depth,
+            ...hookBase,
             durationMs: Date.now() - startTime,
             error: normalizedError
           });
@@ -1404,6 +1487,7 @@ function defineMethod(config) {
     meta: collectLeafMeta(config),
     resolvers: config.resolvers,
     formatter: config.formatter,
+    annotator: config.annotator,
     output: config.output,
     positional: config.positional,
     setup: config.setup,
@@ -1563,7 +1647,8 @@ function defineHook(config) {
     setup: config.setup,
     dispose: config.dispose,
     wrap: config.wrap,
-    observe: config.observe
+    observe: config.observe,
+    annotator: config.annotator
   };
 }
 function declarePlugin(config) {
@@ -2002,7 +2087,14 @@ function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configur
   }
   return byId;
 }
-function bindValue(target, key, entry, callType = "surface", ctx) {
+function bindValue({
+  target,
+  key,
+  entry,
+  bindMode = "surface",
+  ctx,
+  frameworkOrigin = false
+}) {
   if (entry.pluginType === "property" && entry.getValue) {
     Object.defineProperty(target, key, {
       get: entry.getValue,
@@ -2010,7 +2102,7 @@ function bindValue(target, key, entry, callType = "surface", ctx) {
       configurable: true
     });
   } else {
-    const value = callType === "internal" && entry.pluginType === "method" ? entry.bindInternal?.(ctx) ?? entry.internalValue ?? entry.value : entry.value;
+    const value = bindMode === "internal" && entry.pluginType === "method" ? entry.bindInternal?.({ ctx, frameworkOrigin }) ?? entry.internalValue ?? entry.value : entry.value;
     Object.defineProperty(target, key, {
       value,
       writable: true,
@@ -2028,7 +2120,12 @@ function buildSurface(context, ...maps) {
   sdk[CONTEXT] = context;
   return sdk;
 }
-function buildImports(plugins, importBindings, ctx) {
+function buildImports({
+  plugins,
+  importBindings,
+  ctx,
+  frameworkOrigin = false
+}) {
   const imports = {};
   for (const { binding, id, optional } of importBindings) {
     const entry = plugins[id];
@@ -2041,10 +2138,31 @@ function buildImports(plugins, importBindings, ctx) {
       });
       continue;
     }
-    bindValue(imports, binding, entry, "internal", ctx);
+    bindValue({
+      target: imports,
+      key: binding,
+      entry,
+      bindMode: "internal",
+      ctx,
+      frameworkOrigin
+    });
   }
   return imports;
 }
+function bindInternalTwin({
+  ctx,
+  frameworkOrigin,
+  withContext,
+  internalValue
+}) {
+  if (ctx) {
+    return (...args) => withContext(childCallContext(ctx))(...args);
+  }
+  if (frameworkOrigin) {
+    return (...args) => withContext(rootCallContext({ callOrigin: "internal" }))(...args);
+  }
+  return internalValue;
+}
 function mirrorLegacyRootKeys(context, rootKeys, meta) {
   const exports = {};
   for (const [name, value] of Object.entries(rootKeys)) {
@@ -2108,7 +2226,11 @@ function bindResolver(resolver, plugins) {
     case "info":
       return { type: "info", text: resolver.text };
     case "object": {
-      const imports = buildImports(plugins, resolver.importBindings);
+      const imports = buildImports({
+        plugins,
+        importBindings: resolver.importBindings,
+        frameworkOrigin: true
+      });
       const bound = {
         type: "object",
         requireParameters: resolver.requireParameters
@@ -2149,7 +2271,11 @@ function bindResolver(resolver, plugins) {
       return bound;
     }
     case "dynamic": {
-      const imports = buildImports(plugins, resolver.importBindings);
+      const imports = buildImports({
+        plugins,
+        importBindings: resolver.importBindings,
+        frameworkOrigin: true
+      });
       const {
         getContext: getContext2,
         listItems,
@@ -2204,7 +2330,11 @@ function bindDefinitions(definitions, plugins) {
   return out;
 }
 function bindFormatter(formatter, plugins) {
-  const imports = buildImports(plugins, formatter.importBindings);
+  const imports = buildImports({
+    plugins,
+    importBindings: formatter.importBindings,
+    frameworkOrigin: true
+  });
   const bound = { format: formatter.format };
   const { getContext: getContext2 } = formatter;
   if (getContext2)
@@ -2292,17 +2422,32 @@ function buildMethodEntries(descriptors, context, states) {
       // Replaced below; never called.
       value: () => void 0
     };
-    const callRun = (input, ctx) => descriptor.run({
-      imports: buildImports(plugins, descriptor.importBindings, ctx),
-      state: states.get(id),
-      input
-    });
+    const callRun = (input, ctx) => {
+      const callContext = ctx ?? rootCallContext();
+      return descriptor.run({
+        imports: buildImports({
+          plugins,
+          importBindings: descriptor.importBindings,
+          ctx: callContext
+        }),
+        state: states.get(id),
+        input,
+        callContext,
+        annotate: (metadata) => {
+          Object.assign(callContext.annotations, metadata);
+        }
+      });
+    };
     const fold = (coreFn) => (input, ctx) => {
       let next = (i) => coreFn(i, ctx);
       for (const wrap of entry.chain) {
         const inner = next;
         next = (i) => wrap.run({
-          imports: buildImports(plugins, wrap.owner.importBindings, ctx),
+          imports: buildImports({
+            plugins,
+            importBindings: wrap.owner.importBindings,
+            ctx
+          }),
           next: inner,
           input: i,
           // Overwritten by the chain item's own closure with the owning
@@ -2313,6 +2458,8 @@ function buildMethodEntries(descriptors, context, states) {
       return next(input);
     };
     const sdk = { context };
+    const methodAnnotator = descriptor.annotator;
+    const boundAnnotator = methodAnnotator ? (input) => methodAnnotator({ input }) : void 0;
     if (out.type === "list") {
       entry.value = createPaginatedFunction(
         fold(callRun),
@@ -2322,6 +2469,7 @@ function buildMethodEntries(descriptors, context, states) {
           name: descriptor.name,
           defaultPageSize: out.defaultPageSize,
           adaptPage: out.adaptPage,
+          annotator: boundAnnotator,
           getDeprecation: () => entry.meta?.deprecation
         }
       );
@@ -2333,6 +2481,7 @@ function buildMethodEntries(descriptors, context, states) {
           sdk,
           schema: descriptor.inputSchema,
           name: descriptor.name,
+          annotator: boundAnnotator,
           getDeprecation: () => entry.meta?.deprecation
         }
       );
@@ -2344,6 +2493,7 @@ function buildMethodEntries(descriptors, context, states) {
           name: descriptor.name,
           schema: descriptor.skipInputValidation ? void 0 : descriptor.inputSchema,
           positional: descriptor.positional,
+          annotator: boundAnnotator,
           // The boundary reads the deprecation LIVE off the entry, so a
           // deprecation merged after build (defineMethodOverride, addPlugin)
           // fires too.
@@ -2364,12 +2514,22 @@ function buildMethodEntries(descriptors, context, states) {
       const internalValue = (...args) => canonicalValue(pack(args), INTERNAL_CALL);
       entry.value = (...args) => canonicalValue(pack(args));
       entry.internalValue = internalValue;
-      entry.bindInternal = (ctx) => ctx ? (...args) => canonicalValue(pack(args), childCallContext(ctx)) : internalValue;
+      entry.bindInternal = (opts) => bindInternalTwin({
+        ...opts,
+        withContext: (context2) => {
+          return (...args) => canonicalValue(pack(args), context2);
+        },
+        internalValue
+      });
       entry.positional = names;
     } else {
       const internalValue = (input) => canonicalValue(input, INTERNAL_CALL);
       entry.internalValue = internalValue;
-      entry.bindInternal = (ctx) => ctx ? (input) => canonicalValue(input, childCallContext(ctx)) : internalValue;
+      entry.bindInternal = (opts) => bindInternalTwin({
+        ...opts,
+        withContext: (context2) => (input) => canonicalValue(input, context2),
+        internalValue
+      });
     }
     plugins[id] = entry;
   }
@@ -2395,8 +2555,14 @@ function buildEagerArtifacts(descriptors, context, states) {
       if (!dispose) return;
       context.disposers?.push({
         id,
+        // Teardown is framework-internal: an SDK method a `dispose` calls runs
+        // on an internal-origin root (dropped from telemetry).
         dispose: (input) => dispose({
-          imports: buildImports(plugins, descriptor.importBindings),
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings,
+            frameworkOrigin: true
+          }),
           state: states.get(id),
           input
         })
@@ -2406,7 +2572,10 @@ function buildEagerArtifacts(descriptors, context, states) {
       states.set(
         id,
         descriptor.setup ? descriptor.setup({
-          imports: buildImports(plugins, descriptor.importBindings)
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings
+          })
         }) : void 0
       );
       recordDisposer();
@@ -2418,14 +2587,20 @@ function buildEagerArtifacts(descriptors, context, states) {
       states.set(
         id,
         descriptor.setup ? descriptor.setup({
-          imports: buildImports(plugins, descriptor.importBindings)
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings
+          })
         }) : void 0
       );
     } else {
       states.set(
         id,
         descriptor.setup ? descriptor.setup({
-          imports: buildImports(plugins, descriptor.importBindings)
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings
+          })
         }) : void 0
       );
       if (descriptor.privileged) {
@@ -2443,7 +2618,7 @@ function buildEagerArtifacts(descriptors, context, states) {
           pluginType: "property",
           name: descriptor.name,
           getValue: () => get({
-            imports: buildImports(plugins, importBindings),
+            imports: buildImports({ plugins, importBindings }),
             state: states.get(id)
           }),
           meta: descriptor.meta,
@@ -2479,7 +2654,7 @@ function resolvePlugin(sdk, ref) {
     return entry.getValue();
   }
   if (entry.pluginType === "method" && entry.internalValue) {
-    return entry.internalValue;
+    return entry.bindInternal?.({ frameworkOrigin: true }) ?? entry.internalValue;
   }
   return entry.value;
 }
@@ -2514,7 +2689,7 @@ function resolveAggregates(descriptors, context) {
     if (descriptor.pluginType !== "aggregate") continue;
     const exports = {};
     for (const [binding, child] of Object.entries(descriptor.exports)) {
-      bindValue(exports, binding, plugins[child.id]);
+      bindValue({ target: exports, key: binding, entry: plugins[child.id] });
     }
     plugins[id] = { pluginType: "aggregate", name: descriptor.name, exports };
   }
@@ -2557,23 +2732,39 @@ function assembleHooks(descriptors, context, states) {
   const plugins = context.plugins;
   for (const id of topoOrder(descriptors)) {
     const descriptor = descriptors.get(id);
-    if (!descriptor || descriptor.pluginType !== "hook" || !descriptor.observe) {
+    if (!descriptor || descriptor.pluginType !== "hook" || !descriptor.observe && !descriptor.annotator) {
       continue;
     }
-    const { observe } = descriptor;
-    const imports = buildImports(plugins, descriptor.importBindings);
+    const { observe, annotator } = descriptor;
     const state = states.get(id);
     const contributed = {};
-    if (observe.onMethodStart) {
-      const onStart = observe.onMethodStart;
-      contributed.onMethodStart = (input) => {
-        runIsolatedObserver(() => onStart({ imports, input, state }));
-      };
+    if (observe?.onMethodStart || observe?.onMethodEnd) {
+      const imports = buildImports({
+        plugins,
+        importBindings: descriptor.importBindings,
+        frameworkOrigin: true
+      });
+      if (observe.onMethodStart) {
+        const onStart = observe.onMethodStart;
+        contributed.onMethodStart = (input) => {
+          runIsolatedObserver(() => onStart({ imports, input, state }));
+        };
+      }
+      if (observe.onMethodEnd) {
+        const onEnd = observe.onMethodEnd;
+        contributed.onMethodEnd = (input) => {
+          runIsolatedObserver(() => onEnd({ imports, input, state }));
+        };
+      }
     }
-    if (observe.onMethodEnd) {
-      const onEnd = observe.onMethodEnd;
-      contributed.onMethodEnd = (input) => {
-        runIsolatedObserver(() => onEnd({ imports, input, state }));
+    if (annotator) {
+      const annotatorFn = annotator;
+      contributed.annotator = ({ methodName, input }) => {
+        try {
+          return annotatorFn({ methodName, input, state });
+        } catch {
+          return {};
+        }
       };
     }
     context.hooks = buildHooks(context.hooks, contributed);
@@ -2607,7 +2798,11 @@ function createSdk(root, options) {
       pluginSurface = plugins2[plugin.id].exports;
     } else {
       pluginSurface = {};
-      bindValue(pluginSurface, plugin.name, plugins2[plugin.id]);
+      bindValue({
+        target: pluginSurface,
+        key: plugin.name,
+        entry: plugins2[plugin.id]
+      });
     }
     for (const key of Object.keys(legacyExports)) context.surface[key] = key;
     if (plugin.pluginType === "aggregate") {
@@ -2624,7 +2819,7 @@ function createSdk(root, options) {
   if (root.pluginType === "method" || root.pluginType === "property") {
     context.surface[root.name] = root.id;
     const sdk = buildSurface(context);
-    bindValue(sdk, root.name, plugins[root.id]);
+    bindValue({ target: sdk, key: root.name, entry: plugins[root.id] });
     return sdk;
   }
   if (root.pluginType === "aggregate")
@@ -2656,7 +2851,7 @@ function addModelPlugin(sdk, plugin, options = {}) {
       context.surface[binding] = child.id;
     }
   } else {
-    bindValue(sdk, plugin.name, entry);
+    bindValue({ target: sdk, key: plugin.name, entry });
     context.surface[plugin.name] = plugin.id;
   }
 }