@zapier/kitcore 0.13.0 → 0.15.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",
@@ -2692,7 +2771,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 +2784,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 +2799,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
         }
       );
     }
@@ -4382,6 +4465,392 @@ function createCorePlugin(options) {
     }
   });
 }
+
+// src/transport/attempt-http-request.ts
+import { z as z9 } from "zod";
+
+// src/transport/authorize-http-request.ts
+import { z as z5 } from "zod";
+function describeUnclaimedConnection(connection) {
+  const delimiterIndex = connection.indexOf(":");
+  if (delimiterIndex === -1) {
+    return 'no auth provider claimed this connection, and it carries no "scheme:" prefix';
+  }
+  return `no auth provider claimed the "${connection.slice(0, delimiterIndex)}" connection scheme`;
+}
+var authorizeHttpRequestPlugin = defineMethod({
+  name: "authorizeHttpRequest",
+  namespace: "kitcore",
+  inputSchema: z5.custom(),
+  skipInputValidation: true,
+  run: async ({ input }) => {
+    const { connection } = input.request;
+    if (connection != null) {
+      throw createCoreError({
+        code: CoreErrorCode.Unknown,
+        message: `authorizeHttpRequest: ${describeUnclaimedConnection(connection)}, so the request was not sent.`
+      });
+    }
+    return input.request;
+  }
+});
+
+// src/transport/dispatch-http-request.ts
+import { z as z6 } from "zod";
+function toFetchInput(request) {
+  const init = { ...request };
+  const { url } = request;
+  delete init.url;
+  delete init.connection;
+  return { url, init };
+}
+var dispatchHttpRequestPlugin = defineMethod({
+  name: "dispatchHttpRequest",
+  namespace: "kitcore",
+  inputSchema: z6.custom(),
+  skipInputValidation: true,
+  run: async ({ input }) => {
+    const { url, init } = toFetchInput(input.request);
+    return fetch(url, init);
+  }
+});
+
+// src/transport/prepare-http-request.ts
+import { z as z7 } from "zod";
+var prepareHttpRequestPlugin = defineMethod({
+  name: "prepareHttpRequest",
+  namespace: "kitcore",
+  inputSchema: z7.custom(),
+  skipInputValidation: true,
+  run: async ({ input }) => input.request
+});
+
+// src/transport/receive-http-response.ts
+import { z as z8 } from "zod";
+var receiveHttpResponsePlugin = defineMethod({
+  name: "receiveHttpResponse",
+  namespace: "kitcore",
+  inputSchema: z8.custom(),
+  skipInputValidation: true,
+  run: async ({ input }) => input.response
+});
+
+// src/transport/attempt-http-request.ts
+var attemptHttpRequestPlugin = defineMethod({
+  name: "attemptHttpRequest",
+  namespace: "kitcore",
+  imports: [
+    declareDefault({ plugin: prepareHttpRequestPlugin }),
+    declareDefault({ plugin: authorizeHttpRequestPlugin }),
+    declareDefault({ plugin: dispatchHttpRequestPlugin }),
+    declareDefault({ plugin: receiveHttpResponsePlugin })
+  ],
+  inputSchema: z9.custom(),
+  skipInputValidation: true,
+  run: async ({ input, imports }) => {
+    const { attempt } = input;
+    const preparedRequest = await imports.prepareHttpRequest({
+      request: input.request,
+      attempt
+    });
+    const authorizedRequest = await imports.authorizeHttpRequest({
+      request: preparedRequest,
+      attempt
+    });
+    const response = await imports.dispatchHttpRequest({
+      request: authorizedRequest,
+      attempt
+    });
+    return imports.receiveHttpResponse({
+      request: authorizedRequest,
+      response,
+      attempt
+    });
+  }
+});
+
+// src/transport/initialize-http-request.ts
+import { z as z10 } from "zod";
+function isReplayableBody(body) {
+  if (body == null || typeof body !== "object") return true;
+  return typeof Blob !== "undefined" && body instanceof Blob || // File extends Blob
+  typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || body instanceof ArrayBuffer || ArrayBuffer.isView(body);
+}
+function withStringUrl(request) {
+  return typeof request.url === "string" ? request : { ...request, url: String(request.url) };
+}
+var initializeHttpRequestPlugin = defineMethod({
+  name: "initializeHttpRequest",
+  namespace: "kitcore",
+  inputSchema: z10.custom(),
+  skipInputValidation: true,
+  run: async ({ input }) => {
+    const request = withStringUrl(input.request);
+    return {
+      ...input.operation,
+      request,
+      replayable: isReplayableBody(request.body)
+    };
+  }
+});
+
+// src/transport/retry-http-request.ts
+var RETRY_HTTP_REQUEST_OPTIONS_ID = "kitcore/retryHttpRequestOptions";
+var retryHttpRequestOptionsPluginRef = declareOptionalProperty({ id: RETRY_HTTP_REQUEST_OPTIONS_ID });
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_MAX_DELAY_MILLISECONDS = 6e4;
+var DEFAULT_RETRY_STATUSES = [429, 500, 502, 503, 504];
+var DEFAULT_NON_IDEMPOTENT_RETRY_STATUSES = [429];
+var DEFAULT_IDEMPOTENT_METHODS = [
+  "GET",
+  "HEAD",
+  "PUT",
+  "DELETE",
+  "OPTIONS",
+  "TRACE"
+];
+var BASE_BACKOFF_MILLISECONDS = 1e3;
+var JITTER_FACTOR = 0.5;
+function directedDelayMilliseconds(response) {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter) {
+    const seconds = Number.parseInt(retryAfter, 10);
+    if (!Number.isNaN(seconds)) return Math.max(0, seconds * 1e3);
+    const date = Date.parse(retryAfter);
+    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  }
+  const reset = response.headers.get("x-ratelimit-reset");
+  if (reset) {
+    const resetSeconds = Number.parseInt(reset, 10);
+    if (!Number.isNaN(resetSeconds)) {
+      return Math.max(0, resetSeconds * 1e3 - Date.now());
+    }
+  }
+  return void 0;
+}
+function backoffMilliseconds(attemptNumber) {
+  const base = BASE_BACKOFF_MILLISECONDS * 2 ** (attemptNumber - 1);
+  return base + Math.random() * JITTER_FACTOR * base;
+}
+function abortReason(signal) {
+  const reason = signal?.reason;
+  return reason ?? new Error("The request was aborted.");
+}
+function sleep(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(finish, milliseconds);
+    function finish() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", cancel);
+      resolve();
+    }
+    function cancel() {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    }
+    if (signal?.aborted) return cancel();
+    signal?.addEventListener("abort", cancel, { once: true });
+  });
+}
+function isIdempotent(request, idempotentMethods) {
+  const method = (request.method ?? "GET").toUpperCase();
+  return idempotentMethods.includes(method);
+}
+var retryHttpRequestPlugin = defineHook({
+  name: "retryHttpRequest",
+  imports: [attemptHttpRequestPlugin, retryHttpRequestOptionsPluginRef],
+  wrap: {
+    attemptHttpRequest: async ({ input, imports, next }) => {
+      const options = imports.retryHttpRequestOptions ?? {};
+      const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+      const maxDelayMilliseconds = options.maxDelayMilliseconds ?? DEFAULT_MAX_DELAY_MILLISECONDS;
+      const idempotentMethods = options.idempotentMethods ?? DEFAULT_IDEMPOTENT_METHODS;
+      const statuses = isIdempotent(input.request, idempotentMethods) ? options.retryStatuses ?? DEFAULT_RETRY_STATUSES : options.nonIdempotentRetryStatuses ?? DEFAULT_NON_IDEMPOTENT_RETRY_STATUSES;
+      for (let attemptNumber = 1; ; attemptNumber++) {
+        const attempt = {
+          ...input.attempt,
+          attemptNumber,
+          // Per-attempt scratch: a cross-stage handoff from a previous attempt
+          // describes a request that is no longer in flight. `operation` rides
+          // through unchanged, so the id and the caller's original request are
+          // the same for every attempt.
+          state: {}
+        };
+        let response;
+        try {
+          response = await next({ ...input, attempt });
+        } catch (error) {
+          if (!options.retryOnError || !canRetry(
+            attemptNumber,
+            maxAttempts,
+            input.attempt.operation.replayable
+          )) {
+            throw error;
+          }
+          await sleep(
+            Math.min(backoffMilliseconds(attemptNumber), maxDelayMilliseconds),
+            attempt.signal
+          );
+          continue;
+        }
+        if (!statuses.includes(response.status) || !canRetry(
+          attemptNumber,
+          maxAttempts,
+          input.attempt.operation.replayable
+        )) {
+          return response;
+        }
+        const directed = directedDelayMilliseconds(response);
+        if (directed != null && directed > maxDelayMilliseconds)
+          return response;
+        const delay = Math.min(
+          directed ?? backoffMilliseconds(attemptNumber),
+          maxDelayMilliseconds
+        );
+        await response.body?.cancel().catch(() => {
+        });
+        await sleep(delay, attempt.signal);
+      }
+    }
+  }
+});
+function canRetry(attemptNumber, maxAttempts, replayable) {
+  return attemptNumber < maxAttempts && replayable;
+}
+
+// src/transport/send-http-request.ts
+import { z as z11 } from "zod";
+function createOperationId() {
+  return globalThis.crypto?.randomUUID?.() ?? `http-${Date.now()}`;
+}
+var sendHttpRequestPlugin = defineMethod({
+  name: "sendHttpRequest",
+  namespace: "kitcore",
+  imports: [
+    declareDefault({ plugin: initializeHttpRequestPlugin }),
+    declareDefault({ plugin: attemptHttpRequestPlugin })
+  ],
+  inputSchema: z11.custom(),
+  skipInputValidation: true,
+  run: async ({ input, imports }) => {
+    const start2 = {
+      operationId: createOperationId(),
+      signal: input.signal
+    };
+    const operation = await imports.initializeHttpRequest({
+      request: input,
+      operation: start2
+    });
+    return imports.attemptHttpRequest({
+      request: operation.request,
+      attempt: {
+        attemptNumber: 1,
+        operation,
+        signal: operation.signal,
+        state: {}
+      }
+    });
+  }
+});
+
+// src/transport/fetch.ts
+import { z as z12 } from "zod";
+var fetchPlugin = defineMethod({
+  name: "fetch",
+  namespace: "kitcore",
+  imports: [declareDefault({ plugin: sendHttpRequestPlugin })],
+  positional: ["url", "init"],
+  inputSchema: z12.custom(),
+  skipInputValidation: true,
+  run: ({ input, imports }) => {
+    const { url, init } = input;
+    return imports.sendHttpRequest({ url, ...init });
+  }
+});
+
+// src/transport/redact.ts
+var CREDENTIAL_HEADERS = ["authorization", "x-api-key"];
+function maskSecret(secret) {
+  if (secret.length > 12) {
+    return `${secret.slice(0, 4)}...${secret.slice(-4)}`;
+  }
+  return `${secret.charAt(0)}...`;
+}
+function maskCredentialHeader(value) {
+  const spaceIndex = value.indexOf(" ");
+  if (spaceIndex > 0 && spaceIndex < value.length - 1) {
+    return `${value.slice(0, spaceIndex + 1)}${maskSecret(value.slice(spaceIndex + 1))}`;
+  }
+  return maskSecret(value);
+}
+function redactHeaders(headers) {
+  if (!headers) return headers;
+  const normalized = new Headers(headers);
+  for (const [name, value] of normalized.entries()) {
+    if (CREDENTIAL_HEADERS.includes(name.toLowerCase())) {
+      normalized.set(name, maskCredentialHeader(value));
+    }
+  }
+  return Object.fromEntries(normalized);
+}
+function redactHttpRequest(request) {
+  const redacted = { ...request };
+  if (request.headers) redacted.headers = redactHeaders(request.headers);
+  if (request.connection != null) {
+    redacted.connection = maskSecret(request.connection);
+  }
+  return redacted;
+}
+
+// src/connections/default-connection-scheme.ts
+import { z as z13 } from "zod";
+var defaultConnectionSchemePlugin = defineMethod({
+  name: "defaultConnectionScheme",
+  namespace: "kitcore",
+  inputSchema: z13.custom(),
+  skipInputValidation: true,
+  run: () => void 0
+});
+
+// src/connections/normalize-connection.ts
+import { z as z14 } from "zod";
+var normalizeConnectionPlugin = defineMethod({
+  name: "normalizeConnection",
+  namespace: "kitcore",
+  imports: [declareDefault({ plugin: defaultConnectionSchemePlugin })],
+  inputSchema: z14.custom(),
+  skipInputValidation: true,
+  run: ({ input, imports }) => {
+    const { connection } = input;
+    if (connection == null) {
+      return void 0;
+    }
+    const delimiterIndex = connection.indexOf(":");
+    if (delimiterIndex !== -1) {
+      return {
+        connection,
+        scheme: connection.slice(0, delimiterIndex),
+        value: connection.slice(delimiterIndex + 1)
+      };
+    }
+    const scheme = imports.defaultConnectionScheme({ connection });
+    return {
+      connection,
+      scheme,
+      value: connection
+    };
+  }
+});
+
+// src/connections/resolve-connection.ts
+import { z as z15 } from "zod";
+var resolveConnectionPlugin = defineMethod({
+  name: "resolveConnection",
+  namespace: "kitcore",
+  inputSchema: z15.custom(),
+  skipInputValidation: true,
+  run: ({ input }) => input.connection
+});
 export {
   CONTEXT,
   CORE_ERROR_SYMBOL,
@@ -4392,7 +4861,13 @@ export {
   CoreError,
   CoreErrorCode,
   CoreSignal,
+  RETRY_HTTP_REQUEST_OPTIONS_ID,
+  STABILITY_LEVELS,
+  STABILITY_TITLES,
   addPlugin,
+  applyStabilityLabel,
+  attemptHttpRequestPlugin,
+  authorizeHttpRequestPlugin,
   canonicalInputSchema,
   composePlugins,
   concatLists,
@@ -4410,6 +4885,7 @@ export {
   createPluginStack,
   createPrefixedCursor,
   createSdk,
+  createStabilityNoticeLogger,
   createValidator,
   dangerousContextPlugin,
   declareDefault,
@@ -4419,6 +4895,7 @@ export {
   declarePlugin,
   declareProperty,
   decodeIncomingCursor,
+  defaultConnectionSchemePlugin,
   defaultLogDeprecation,
   defineFormatter,
   defineHook,
@@ -4428,7 +4905,9 @@ export {
   definePlugin,
   defineProperty,
   defineResolver,
+  dispatchHttpRequestPlugin,
   disposeSdk,
+  fetchPlugin,
   fromFunctionPlugin,
   getContext,
   getCoreErrorCause,
@@ -4440,21 +4919,32 @@ export {
   getOutputSchema,
   getRegistryPlugin,
   getSchemaDescription,
+  initializeHttpRequestPlugin,
   isCoreCancelledSignal,
   isCoreError,
   isCoreSignal,
   isNestedMethodCall,
   isPositional,
   isTelemetryNested,
+  normalizeConnectionPlugin,
+  normalizeStability,
   omitExports,
   openEnum,
   paginate,
   paginateBuffered,
   paginateMaxItems,
+  prepareHttpRequestPlugin,
+  receiveHttpResponsePlugin,
+  redactHeaders,
+  redactHttpRequest,
+  resolveConnectionPlugin,
   resolvePlugin,
+  retryHttpRequestOptionsPluginRef,
+  retryHttpRequestPlugin,
   runInMethodScope,
   runWithTelemetryContext,
   selectExports,
+  sendHttpRequestPlugin,
   splitPrefixedCursor,
   toIterable,
   toSnakeCase,