@zapier/kitcore 0.14.0 → 0.16.0

package/dist/index.mjs

@@ -89,6 +89,28 @@ function openEnum(values, description) {
   return z.union([z.enum(values), 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;
@@ -133,6 +155,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,
@@ -148,7 +171,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,
@@ -237,6 +264,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");
@@ -721,6 +762,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
@@ -769,6 +823,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);
@@ -782,7 +848,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) {
@@ -790,6 +856,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();
@@ -856,12 +923,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();
@@ -967,7 +1043,8 @@ function createPaginatedFunction(coreFn, options) {
     adaptPage,
     annotator,
     finalizePage,
-    getDeprecation
+    getDeprecation,
+    getStability
   } = options;
   const pageFunction = createPageFunction(coreFn, {
     sdk,
@@ -981,6 +1058,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();
@@ -1425,6 +1503,7 @@ var LEAF_META_KEYS = [
   "returnType",
   "outputSchema",
   "packages",
+  "stability",
   "experimental",
   "confirm",
   "deprecation",
@@ -2303,8 +2382,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
     });
@@ -2692,7 +2772,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") {
@@ -2704,7 +2785,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 {
@@ -2718,8 +2800,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
         }
       );
     }
@@ -2839,9 +2923,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
@@ -4779,7 +4868,10 @@ export {
   CoreErrorCode,
   CoreSignal,
   RETRY_HTTP_REQUEST_OPTIONS_ID,
+  STABILITY_LEVELS,
+  STABILITY_TITLES,
   addPlugin,
+  applyStabilityLabel,
   attemptHttpRequestPlugin,
   authorizeHttpRequestPlugin,
   canonicalInputSchema,
@@ -4799,6 +4891,7 @@ export {
   createPluginStack,
   createPrefixedCursor,
   createSdk,
+  createStabilityNoticeLogger,
   createValidator,
   dangerousContextPlugin,
   declareDefault,
@@ -4840,6 +4933,7 @@ export {
   isPositional,
   isTelemetryNested,
   normalizeConnectionPlugin,
+  normalizeStability,
   omitExports,
   openEnum,
   paginate,