@zapier/kitcore 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/kitcore
 
+## 0.16.0
+
+### Minor Changes
+
+- cd0616e: Added an optional `callContext` to the `defineProperty` `get` bag, so a property getter can read the current call's context (e.g. its correlation id) when accessed through a method's `imports`. Every method call supplies one, at any depth; it is absent only where no call is in flight — the property bound onto the SDK object itself, and reads from a `setup`-time `imports` bag. Additive — existing property getters are unaffected.
+
+## 0.15.0
+
+### Minor Changes
+
+- f0fe306: Add the API stability ladder: `PluginMeta.stability` (`"stable" | "beta" | "experimental"`) replaces the `experimental` boolean as the authored stability signal. The registry projection normalizes every entry to a concrete `FunctionRegistryEntry.stability`; the `experimental` boolean is deprecated but preserved as an input (`true` normalizes to `"experimental"`) and as a derived read (`stability === "experimental"` — literal by name; the not-stable warning duty lives in `stability` and the runtime notice). New exports: `STABILITY_LEVELS`, `STABILITY_TITLES`, `normalizeStability`, `applyStabilityLabel`, and the `StabilityLevel` type. The method boundary now reports every surface call of a beta / experimental method to `CoreOptions.logStabilityNotice` (default: once-per-process deduped `console.warn`), mirroring the deprecation signal — internal delegation never signals.
+
 ## 0.14.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -30,7 +30,10 @@ __export(index_exports, {
   CoreErrorCode: () => CoreErrorCode,
   CoreSignal: () => CoreSignal,
   RETRY_HTTP_REQUEST_OPTIONS_ID: () => RETRY_HTTP_REQUEST_OPTIONS_ID,
+  STABILITY_LEVELS: () => STABILITY_LEVELS,
+  STABILITY_TITLES: () => STABILITY_TITLES,
   addPlugin: () => addPlugin,
+  applyStabilityLabel: () => applyStabilityLabel,
   attemptHttpRequestPlugin: () => attemptHttpRequestPlugin,
   authorizeHttpRequestPlugin: () => authorizeHttpRequestPlugin,
   canonicalInputSchema: () => canonicalInputSchema,
@@ -50,6 +53,7 @@ __export(index_exports, {
   createPluginStack: () => createPluginStack,
   createPrefixedCursor: () => createPrefixedCursor,
   createSdk: () => createSdk,
+  createStabilityNoticeLogger: () => createStabilityNoticeLogger,
   createValidator: () => createValidator,
   dangerousContextPlugin: () => dangerousContextPlugin,
   declareDefault: () => declareDefault,
@@ -91,6 +95,7 @@ __export(index_exports, {
   isPositional: () => isPositional,
   isTelemetryNested: () => isTelemetryNested,
   normalizeConnectionPlugin: () => normalizeConnectionPlugin,
+  normalizeStability: () => normalizeStability,
   omitExports: () => omitExports,
   openEnum: () => openEnum,
   paginate: () => paginate,
@@ -210,6 +215,28 @@ function openEnum(values, description) {
   return import_zod.z.union([import_zod.z.enum(values), import_zod.z.string()]).describe(description);
 }
 
+// src/utils/stability.ts
+var STABILITY_LEVELS = ["stable", "beta", "experimental"];
+var STABILITY_TITLES = {
+  stable: "Stable",
+  beta: "Beta",
+  experimental: "Experimental"
+};
+function normalizeStability(meta) {
+  if (meta.stability !== void 0) {
+    return STABILITY_LEVELS.includes(meta.stability) ? meta.stability : "experimental";
+  }
+  return meta.experimental ? "experimental" : "stable";
+}
+function applyStabilityLabel({
+  description,
+  stability,
+  placement = "suffix"
+}) {
+  if (stability === void 0 || stability === "stable") return description;
+  return placement === "prefix" ? `[${STABILITY_TITLES[stability]}] ${description}` : `${description} (${stability})`;
+}
+
 // src/registry.ts
 function resolveCategoryDefinition(ref) {
   const def = typeof ref === "string" ? { key: ref } : ref;
@@ -254,6 +281,7 @@ function buildRegistry({
     return typeof rootProperty === "object" && rootProperty !== null;
   }).map((key) => {
     const m = meta[key];
+    const stability = normalizeStability(m);
     return {
       name: key,
       description: m.description,
@@ -269,7 +297,11 @@ function buildRegistry({
       ),
       resolvers: resolvers?.[key],
       formatter: formatters?.[key],
-      experimental: m.experimental,
+      stability,
+      // Deprecated derived read, literal by name: only the experimental
+      // tier reads true. Beta reads false — the "not stable" warning duty
+      // lives in `stability` and the runtime notice, not this boolean.
+      experimental: stability === "experimental",
       packages: m.packages,
       confirm: m.confirm ?? (m.type === "delete" ? "delete" : void 0),
       deprecation: m.deprecation,
@@ -358,6 +390,20 @@ function createDeprecationLogger(tag) {
   };
 }
 var { logDeprecation, resetDeprecationWarnings } = createDeprecationLogger("core");
+function createStabilityNoticeLogger(tag) {
+  const loggedNotices = /* @__PURE__ */ new Set();
+  return {
+    logStabilityNotice(message) {
+      if (loggedNotices.has(message)) return;
+      loggedNotices.add(message);
+      console.warn(`[${tag}] ${message}`);
+    },
+    resetStabilityNotices() {
+      loggedNotices.clear();
+    }
+  };
+}
+var { logStabilityNotice, resetStabilityNotices } = createStabilityNoticeLogger("core");
 
 // src/types/errors.ts
 var CORE_ERROR_SYMBOL = Symbol.for("kitcore.error");
@@ -840,6 +886,19 @@ function defaultLogDeprecation({
 }) {
   logDeprecation(`${methodName}() is deprecated. ${deprecation.message}`);
 }
+var STABILITY_NOTICE_DETAILS = {
+  beta: "Its API shape is settled, but it is not yet covered by stable-tier guarantees.",
+  experimental: "It may change shape or disappear without notice."
+};
+function defaultLogStabilityNotice({
+  methodName,
+  stability
+}) {
+  if (stability === "stable") return;
+  logStabilityNotice(
+    `${methodName}() is a ${stability} API. ${STABILITY_NOTICE_DETAILS[stability]}`
+  );
+}
 var CORE_OPTIONS_ID = "kitcore/coreOptions";
 
 // src/utils/function-utils.ts
@@ -888,6 +947,18 @@ function signalDeprecation(context, methodName, getDeprecation) {
   const handler = resolveCoreOptions(context)?.logDeprecation ?? defaultLogDeprecation;
   runIsolatedObserver(() => handler(warning));
 }
+function signalStability(context, methodName, getStability) {
+  if (isInsideObserver()) return;
+  const stability = getStability?.();
+  if (!stability || stability === "stable") return;
+  const notice = {
+    type: "stability",
+    methodName,
+    stability
+  };
+  const handler = resolveCoreOptions(context)?.logStabilityNotice ?? defaultLogStabilityNotice;
+  runIsolatedObserver(() => handler(notice));
+}
 function normalizeError(error, adaptError) {
   if (error instanceof Error) return error;
   const message = typeof error === "object" && error !== null && "message" in error && typeof error.message === "string" ? error.message : String(error);
@@ -901,7 +972,7 @@ function normalizeError(error, adaptError) {
   );
 }
 function createFunction(coreFn, options) {
-  const { sdk, schema, name, annotator, getDeprecation } = options;
+  const { sdk, schema, name, annotator, getDeprecation, getStability } = options;
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: async function(callOptions) {
@@ -909,6 +980,7 @@ function createFunction(coreFn, options) {
       const context = resolveCallContext(internal);
       if (!isCallContext(internal) && internal !== INTERNAL_CALL) {
         signalDeprecation(sdk.context, functionName, getDeprecation);
+        signalStability(sdk.context, functionName, getStability);
       }
       return runInMethodScope(async () => {
         const startTime = Date.now();
@@ -975,12 +1047,21 @@ function createFunction(coreFn, options) {
   return namedFunctions[functionName];
 }
 function createRawFunction(coreFn, options) {
-  const { sdk, name, schema, positional, annotator, getDeprecation } = options;
+  const {
+    sdk,
+    name,
+    schema,
+    positional,
+    annotator,
+    getDeprecation,
+    getStability
+  } = options;
   return function(rawInput) {
     const internal = arguments[1];
     const context = resolveCallContext(internal);
     if (!isCallContext(internal) && internal !== INTERNAL_CALL) {
       signalDeprecation(sdk.context, name, getDeprecation);
+      signalStability(sdk.context, name, getStability);
     }
     return runInMethodScope(() => {
       const startTime = Date.now();
@@ -1086,7 +1167,8 @@ function createPaginatedFunction(coreFn, options) {
     adaptPage,
     annotator,
     finalizePage,
-    getDeprecation
+    getDeprecation,
+    getStability
   } = options;
   const pageFunction = createPageFunction(coreFn, {
     sdk,
@@ -1100,6 +1182,7 @@ function createPaginatedFunction(coreFn, options) {
       const context = resolveCallContext(internal);
       if (!isCallContext(internal) && internal !== INTERNAL_CALL) {
         signalDeprecation(sdk.context, functionName, getDeprecation);
+        signalStability(sdk.context, functionName, getStability);
       }
       return runInMethodScope(() => {
         const startTime = Date.now();
@@ -1544,6 +1627,7 @@ var LEAF_META_KEYS = [
   "returnType",
   "outputSchema",
   "packages",
+  "stability",
   "experimental",
   "confirm",
   "deprecation",
@@ -2422,8 +2506,9 @@ function bindValue({
   frameworkOrigin = false
 }) {
   if (entry.pluginType === "property" && entry.getValue) {
+    const getValue = entry.getValue;
     Object.defineProperty(target, key, {
-      get: entry.getValue,
+      get: ctx ? () => getValue(ctx) : getValue,
       enumerable: true,
       configurable: true
     });
@@ -2811,7 +2896,8 @@ function buildMethodEntries(descriptors, context, states) {
           // (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
+          getDeprecation: () => entry.meta?.deprecation,
+          getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     } else if (out.type === "item") {
@@ -2823,7 +2909,8 @@ function buildMethodEntries(descriptors, context, states) {
           schema: descriptor.inputSchema,
           name: descriptor.name,
           annotator: boundAnnotator,
-          getDeprecation: () => entry.meta?.deprecation
+          getDeprecation: () => entry.meta?.deprecation,
+          getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     } else {
@@ -2837,8 +2924,10 @@ function buildMethodEntries(descriptors, context, states) {
           annotator: boundAnnotator,
           // The boundary reads the deprecation LIVE off the entry, so a
           // deprecation merged after build (defineMethodOverride, addPlugin)
-          // fires too.
-          getDeprecation: () => entry.meta?.deprecation
+          // fires too. Same for the stability level, normalized from the
+          // entry meta (declared level or legacy `experimental` boolean).
+          getDeprecation: () => entry.meta?.deprecation,
+          getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     }
@@ -2958,9 +3047,14 @@ function buildEagerArtifacts(descriptors, context, states) {
         plugins[id] = {
           pluginType: "property",
           name: descriptor.name,
-          getValue: () => get({
-            imports: buildImports({ plugins, importBindings }),
-            state: states.get(id)
+          getValue: (callContext) => get({
+            imports: buildImports({
+              plugins,
+              importBindings,
+              ctx: callContext
+            }),
+            state: states.get(id),
+            callContext
           }),
           meta: descriptor.meta,
           dynamicMembers: descriptor.dynamicMembers
@@ -4899,7 +4993,10 @@ var resolveConnectionPlugin = defineMethod({
   CoreErrorCode,
   CoreSignal,
   RETRY_HTTP_REQUEST_OPTIONS_ID,
+  STABILITY_LEVELS,
+  STABILITY_TITLES,
   addPlugin,
+  applyStabilityLabel,
   attemptHttpRequestPlugin,
   authorizeHttpRequestPlugin,
   canonicalInputSchema,
@@ -4919,6 +5016,7 @@ var resolveConnectionPlugin = defineMethod({
   createPluginStack,
   createPrefixedCursor,
   createSdk,
+  createStabilityNoticeLogger,
   createValidator,
   dangerousContextPlugin,
   declareDefault,
@@ -4960,6 +5058,7 @@ var resolveConnectionPlugin = defineMethod({
   isPositional,
   isTelemetryNested,
   normalizeConnectionPlugin,
+  normalizeStability,
   omitExports,
   openEnum,
   paginate,