@zapier/zapier-sdk 0.97.1 → 0.98.1

package/dist/{chunk-MAEVVN2L.cjs → chunk-IZRPXHWO.cjs}

@@ -68,6 +68,13 @@ function getNegatable(schema) {
 function openEnum(values, description) {
   return zod.z.union([zod.z.enum(values), zod.z.string()]).describe(description);
 }
+var STABILITY_LEVELS = ["stable", "beta", "experimental"];
+function normalizeStability(meta) {
+  if (meta.stability !== void 0) {
+    return STABILITY_LEVELS.includes(meta.stability) ? meta.stability : "experimental";
+  }
+  return meta.experimental ? "experimental" : "stable";
+}
 function resolveCategoryDefinition(ref) {
   const def = typeof ref === "string" ? { key: ref } : ref;
   const title = def.title ?? toTitleCase(def.key);
@@ -111,6 +118,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,
@@ -126,7 +134,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,
@@ -211,6 +223,20 @@ function createDeprecationLogger(tag) {
   };
 }
 var { logDeprecation} = 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} = createStabilityNoticeLogger("core");
 var CORE_ERROR_SYMBOL = Symbol.for("kitcore.error");
 var CoreErrorCode = {
   Validation: "VALIDATION_ERROR",
@@ -622,6 +648,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";
 function resolveCoreOptions(context) {
   const entry = context.plugins?.[CORE_OPTIONS_ID];
@@ -668,6 +707,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);
@@ -681,7 +732,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) {
@@ -689,6 +740,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();
@@ -755,12 +807,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();
@@ -866,7 +927,8 @@ function createPaginatedFunction(coreFn, options) {
     adaptPage,
     annotator,
     finalizePage,
-    getDeprecation
+    getDeprecation,
+    getStability
   } = options;
   const pageFunction = createPageFunction(coreFn, {
     sdk,
@@ -880,6 +942,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();
@@ -1318,6 +1381,7 @@ var LEAF_META_KEYS = [
   "returnType",
   "outputSchema",
   "packages",
+  "stability",
   "experimental",
   "confirm",
   "deprecation",
@@ -2155,8 +2219,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
     });
@@ -2543,7 +2608,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") {
@@ -2555,7 +2621,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 {
@@ -2569,8 +2636,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
         }
       );
     }
@@ -2690,9 +2759,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
@@ -5598,6 +5672,11 @@ function createSemaphore(maxPermits) {
     }
   };
 }
+
+// src/api/correlation.ts
+var CORRELATION_CALL_ID = Symbol(
+  "zapier.correlationCallId"
+);
 var ClientCredentialsObjectSchema = zod.z.object({
   type: zod.z.enum(["client_credentials"]).optional().meta({ internal: true }),
   clientId: zod.z.string().describe("OAuth client ID for authentication.").meta({ valueHint: "id" }),
@@ -6514,7 +6593,7 @@ function parseDeprecationDate(value) {
 }
 
 // src/sdk-version.ts
-var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.97.1" : void 0) || "unknown";
+var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.98.1" : void 0) || "unknown";
 
 // src/utils/open-url.ts
 var nodePrefix = "node:";
@@ -6776,14 +6855,15 @@ var ZapierApiClient = class {
      * directly and drifting.
      */
     this.rawFetchUrl = async (url, init, pathConfig2) => {
-      if (init?.body && (isPlainObject(init.body) || Array.isArray(init.body))) {
-        init.body = JSON.stringify(init.body);
+      const { [CORRELATION_CALL_ID]: callId, ...fetchInit } = init ?? {};
+      if (fetchInit.body && (isPlainObject(fetchInit.body) || Array.isArray(fetchInit.body))) {
+        fetchInit.body = JSON.stringify(fetchInit.body);
       }
       const builtHeaders = await this.buildHeaders(
-        init,
+        fetchInit,
         pathConfig2
       );
-      const inputHeaders = new Headers(init?.headers ?? {});
+      const inputHeaders = new Headers(fetchInit.headers ?? {});
       const mergedHeaders = new Headers();
       builtHeaders.forEach((value, key) => {
         mergedHeaders.set(key, value);
@@ -6791,11 +6871,11 @@ var ZapierApiClient = class {
       inputHeaders.forEach((value, key) => {
         mergedHeaders.set(key, value);
       });
-      this.applyTelemetryHeaders(mergedHeaders);
+      this.applyTelemetryHeaders({ headers: mergedHeaders, callId });
       let retries = 0;
       while (true) {
         const response = await this.options.fetch(url, {
-          ...init,
+          ...fetchInit,
           headers: mergedHeaders
         });
         if (response.status !== 429) {
@@ -6916,12 +6996,13 @@ var ZapierApiClient = class {
         );
         const askStatementIds = askStatementIdsHeader ? JSON.parse(askStatementIdsHeader) : void 0;
         try {
-          await this.runOneApprovalRound(
-            approvalContext,
-            approvalMode,
-            init?.signal ?? void 0,
-            askStatementIds
-          );
+          await this.runOneApprovalRound({
+            buildContext: approvalContext,
+            mode: approvalMode,
+            signal: init?.signal ?? void 0,
+            askStatementIds,
+            callId: init?.[CORRELATION_CALL_ID]
+          });
         } catch (error) {
           return { response, approvalRoundError: error };
         }
@@ -7063,7 +7144,8 @@ var ZapierApiClient = class {
           method: "GET",
           searchParams: options.searchParams,
           authRequired: options.authRequired,
-          signal: options.signal
+          signal: options.signal,
+          [CORRELATION_CALL_ID]: options[CORRELATION_CALL_ID]
         }),
         initialDelay: options.initialDelayMilliseconds ?? options.initialDelay,
         timeoutMs: options.timeoutMilliseconds ?? options.timeoutMs,
@@ -7358,7 +7440,10 @@ var ZapierApiClient = class {
   // gateway now expects) and the legacy `x-zapier-*` names. The legacy names are
   // kept for backward compatibility with consumers that haven't migrated yet;
   // they can be removed once nothing reads them.
-  applyTelemetryHeaders(headers) {
+  applyTelemetryHeaders({
+    headers,
+    callId
+  }) {
     headers.set("zapier-sdk-version", SDK_VERSION);
     headers.set("x-zapier-sdk-version", SDK_VERSION);
     const sdkService = getZapierSdkService();
@@ -7381,6 +7466,11 @@ var ZapierApiClient = class {
         headers.set("zapier-sdk-package-operation", packageOperation);
       }
     }
+    if (callId) {
+      headers.set("zapier-correlation-id", callId);
+    } else {
+      headers.delete("zapier-correlation-id");
+    }
   }
   // Helper to perform HTTP requests with JSON handling
   async fetchJson(method, path, data, options = {}) {
@@ -7523,7 +7613,13 @@ var ZapierApiClient = class {
    * Caller is responsible for passing a non-"disabled" mode; this method
    * unconditionally creates an approval.
    */
-  async runOneApprovalRound(buildContext, mode, signal, askStatementIds) {
+  async runOneApprovalRound({
+    buildContext,
+    mode,
+    signal,
+    askStatementIds,
+    callId
+  }) {
     const context = buildContext();
     let approvalResponse;
     try {
@@ -7537,7 +7633,8 @@ var ZapierApiClient = class {
           context,
           ...askStatementIds?.length ? { ask_statement_ids: askStatementIds } : {}
         }),
-        signal
+        signal,
+        [CORRELATION_CALL_ID]: callId
       });
     } catch (err) {
       if (isAbortError(err)) throw err;
@@ -7673,7 +7770,10 @@ var ZapierApiClient = class {
         approvalId: approval.id,
         streamUrl,
         signal: streamAbortController.signal,
-        stream: (url, streamInit) => this.streamTrustedJsonUrl(url, streamInit),
+        stream: (url, streamInit) => this.streamTrustedJsonUrl(url, {
+          ...streamInit,
+          [CORRELATION_CALL_ID]: callId
+        }),
         emitEvent: (type, payload) => this.emitEvent(type, payload)
       });
     }
@@ -7682,7 +7782,8 @@ var ZapierApiClient = class {
       () => this.rawFetchUrl(approval.poll_url, {
         method: "GET",
         headers: { Accept: "application/json" },
-        signal
+        signal,
+        [CORRELATION_CALL_ID]: callId
       })
     );
     const pollApprovalUntilComplete = async (isPending, deadlineMs = approvalDeadline) => {
@@ -7874,6 +7975,23 @@ var API_ID = "zapier/api";
 var apiPluginRef = declareProperty({
   id: API_ID
 });
+function withCorrelationId({
+  client,
+  callId
+}) {
+  const stamp = (options) => ({ ...options, [CORRELATION_CALL_ID]: callId });
+  return {
+    get: (path, options) => client.get(path, stamp(options)),
+    post: (path, data, options) => client.post(path, data, stamp(options)),
+    put: (path, data, options) => client.put(path, data, stamp(options)),
+    patch: (path, data, options) => client.patch(path, data, stamp(options)),
+    delete: (path, data, options) => client.delete(path, data, stamp(options)),
+    poll: (path, options) => client.poll(path, stamp(options)),
+    fetch: (path, init) => client.fetch(path, stamp(init)),
+    fetchStream: (path, init) => client.fetchStream(path, stamp(init)),
+    fetchJsonStream: (path, init) => client.fetchJsonStream(path, stamp(init))
+  };
+}
 var apiPlugin = defineProperty({
   namespace: "zapier",
   name: "api",
@@ -7914,7 +8032,7 @@ var apiPlugin = defineProperty({
       callerPackage
     });
   },
-  get: ({ state }) => state
+  get: ({ state, callContext }) => callContext?.callId ? withCorrelationId({ client: state, callId: callContext.callId }) : state
 });
 var RESOLVE_CREDENTIALS_ID = "zapier/resolveCredentials";
 var resolveCredentialsPluginRef = declareProperty({ id: RESOLVE_CREDENTIALS_ID });
@@ -8475,8 +8593,11 @@ var manifestPlugin = defineProperty({
   namespace: "zapier",
   name: "manifest",
   imports: [sdkOptionsPluginRef, apiPluginRef],
+  // Deliberately does not read `imports.api`: at build time that resolves to the
+  // bare shared client, and capturing it here would strip the correlation id off
+  // every slug-resolution request. `get` supplies the reading call's client
+  // instead.
   setup: ({ imports }) => {
-    const api = imports.api;
     const { manifestPath = DEFAULT_CONFIG_PATH, manifest } = imports.sdkOptions ?? {};
     let resolvedManifest;
     async function resolveManifest() {
@@ -8494,7 +8615,10 @@ var manifestPlugin = defineProperty({
       }
       return resolvedManifest;
     };
-    const getVersionedImplementationId = async (appKey) => {
+    const getVersionedImplementationId = async ({
+      appKey,
+      api
+    }) => {
       const resolvedApps = await resolveAppKeys({
         appKeys: [appKey],
         api,
@@ -8504,14 +8628,14 @@ var manifestPlugin = defineProperty({
       if (!resolvedApp) return null;
       return `${resolvedApp.implementationName}@${resolvedApp.version || "latest"}`;
     };
-    const updateManifestEntry = async (options) => {
-      const {
-        appKey,
-        entry,
-        configPath = DEFAULT_CONFIG_PATH,
-        skipWrite = false,
-        manifest: inputManifest
-      } = options;
+    const updateManifestEntry = async ({
+      api,
+      appKey,
+      entry,
+      configPath = DEFAULT_CONFIG_PATH,
+      skipWrite = false,
+      manifest: inputManifest
+    }) => {
       const manifest2 = inputManifest || await readManifestFromFile(configPath) || { apps: {} };
       let existingEntry = findManifestEntry({
         appKey,
@@ -8562,7 +8686,7 @@ var manifestPlugin = defineProperty({
     };
     return {
       getVersionedImplementationId,
-      resolveAppKeys: async ({ appKeys }) => resolveAppKeys({
+      resolveAppKeys: async ({ appKeys, api }) => resolveAppKeys({
         appKeys,
         api,
         manifest: await getResolvedManifest() ?? { apps: {} }
@@ -8575,7 +8699,19 @@ var manifestPlugin = defineProperty({
       updateManifestEntry
     };
   },
-  get: ({ state }) => state
+  // Bind the reading call's API client onto the slug-resolving entry points so
+  // their requests carry that call's correlation id. The manifest-only reads pass
+  // straight through.
+  get: ({ imports, state }) => {
+    const api = imports.api;
+    return {
+      getVersionedImplementationId: (appKey) => state.getVersionedImplementationId({ appKey, api }),
+      resolveAppKeys: ({ appKeys }) => state.resolveAppKeys({ appKeys, api }),
+      getResolvedManifest: state.getResolvedManifest,
+      getManifestConnections: state.getManifestConnections,
+      updateManifestEntry: (options) => state.updateManifestEntry({ ...options, api })
+    };
+  }
 });
 
 // src/plugins/connections/index.ts
@@ -11864,14 +12000,24 @@ var ListConnectionsQuerySchema = connections.ListConnectionsQuerySchema.omit({
   includeShared: zod.z.boolean().optional().describe(
     "Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections."
   ),
-  /** @deprecated Use `expired` instead */
+  // Filters on connection expiry. Not a mirror of a server-side status
+  // field: the API expresses this as the is_expired filter, which we send as
+  // false for "active", true for "expired", and omit for "all".
+  status: zod.z.enum(["active", "expired", "all"]).optional().describe(
+    "Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both."
+  ),
+  /** @deprecated Use `status` instead */
   isExpired: zod.z.boolean().optional().describe("Filter by expired status").meta({
     deprecated: true,
-    deprecationMessage: "Use --expired instead to show only expired connections."
+    deprecationMessage: "Use --status expired instead to show only expired connections, or --status all for both."
   }),
+  /** @deprecated Use `status` instead */
   expired: zod.z.boolean().optional().describe(
     "Show only expired connections (default: only non-expired connections are returned)"
-  ),
+  ).meta({
+    deprecated: true,
+    deprecationMessage: "Use --status expired instead to show only expired connections, or --status all for both."
+  }),
   // Override pageSize to make optional
   pageSize: zod.z.number().min(1).optional().describe("Number of connections per page"),
   // SDK specific property for pagination/iterable helpers
@@ -11997,10 +12143,15 @@ var listConnectionsPlugin = defineMethod({
     if (owner) {
       searchParams.owner = owner;
     }
-    if (input.isExpired !== void 0) {
-      searchParams.is_expired = input.isExpired.toString();
-    } else {
-      searchParams.is_expired = (input.expired ?? false).toString();
+    const expiredFilter = input.isExpired ?? input.expired;
+    if (input.status !== void 0 && expiredFilter !== void 0) {
+      throw new ZapierValidationError(
+        'The "status" option replaces "expired" and "isExpired", so it cannot be combined with either.'
+      );
+    }
+    const status = input.status ?? (expiredFilter ? "expired" : "active");
+    if (status !== "all") {
+      searchParams.is_expired = (status === "expired").toString();
     }
     if (input.cursor) {
       searchParams.offset = input.cursor;
@@ -15661,6 +15812,7 @@ function buildErrorEventWithContext(data, context = {}) {
 function buildMethodCalledEvent(data, context = {}) {
   return {
     ...createBaseEvent(context),
+    correlation_id: data.correlation_id ?? context.correlation_id ?? null,
     method_name: data.method_name ?? null,
     method_module: data.method_module ?? null,
     execution_duration_ms: data.execution_duration_ms,
@@ -15718,6 +15870,7 @@ function makeMethodEndHook(emitMethodCalled) {
     args,
     isPaginated,
     depth,
+    callId,
     callOrigin,
     annotations,
     durationMs,
@@ -15727,6 +15880,9 @@ function makeMethodEndHook(emitMethodCalled) {
     const metadata = readMethodMetadata(annotations);
     emitMethodCalled({
       method_name: methodName,
+      // The per-call correlation id (also the `zapier-correlation-id` header on
+      // this call's requests). Not the `call_context` surface label.
+      correlation_id: callId ?? null,
       execution_duration_ms: durationMs,
       success_flag: !error,
       error_message: error?.message ?? null,