@zapier/zapier-sdk 0.97.0 → 0.98.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.98.0
+
+### Minor Changes
+
+- 9a5ae37: Added `status` to `listConnections`, `findFirstConnection`, and `findUniqueConnection` to filter connections by expiry: `active` (the default, and the existing behaviour), `expired`, or `all` for both. Previously only non-expired connections were returned by default and `expired: true` returned only expired ones, so a single call could never cover both. `expired` and `isExpired` are now deprecated in favour of `status` and still work; combining `status` with either throws a validation error.
+
+## 0.97.1
+
+### Patch Changes
+
+- e45f03b: _This release contains no user-facing changes._
+
 ## 0.97.0
 
 ### Minor Changes

package/README.md

@@ -2254,16 +2254,16 @@ Find the first connection matching the criteria
 
 **Parameters:**
 
-| Name                | Type      | Required | Default | Possible Values | Description                                                                                                                                         |
-| ------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`           | `object`  | ✅       | —       | —               |                                                                                                                                                     |
-| ​ ↳ `search`        | `string`  | ❌       | —       | —               | Search term to filter connections by title                                                                                                          |
-| ​ ↳ `title`         | `string`  | ❌       | —       | —               | Filter connections by exact title match (searches first, then filters locally)                                                                      |
-| ​ ↳ `owner`         | `string`  | ❌       | —       | —               | Filter by owner, 'me' for your own connections or a specific user ID                                                                                |
-| ​ ↳ `app`           | `string`  | ❌       | —       | —               | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github')                                                                          |
-| ​ ↳ `account`       | `string`  | ❌       | —       | —               | Account to filter by                                                                                                                                |
-| ​ ↳ `includeShared` | `boolean` | ❌       | —       | —               | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
-| ​ ↳ `expired`       | `boolean` | ❌       | —       | —               | Show only expired connections (default: only non-expired connections are returned)                                                                  |
+| Name                | Type      | Required | Default | Possible Values            | Description                                                                                                                                         |
+| ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`           | `object`  | ✅       | —       | —                          |                                                                                                                                                     |
+| ​ ↳ `search`        | `string`  | ❌       | —       | —                          | Search term to filter connections by title                                                                                                          |
+| ​ ↳ `title`         | `string`  | ❌       | —       | —                          | Filter connections by exact title match (searches first, then filters locally)                                                                      |
+| ​ ↳ `owner`         | `string`  | ❌       | —       | —                          | Filter by owner, 'me' for your own connections or a specific user ID                                                                                |
+| ​ ↳ `app`           | `string`  | ❌       | —       | —                          | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github')                                                                          |
+| ​ ↳ `account`       | `string`  | ❌       | —       | —                          | Account to filter by                                                                                                                                |
+| ​ ↳ `includeShared` | `boolean` | ❌       | —       | —                          | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
+| ​ ↳ `status`        | `string`  | ❌       | —       | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both.         |
 
 **Returns:** `Promise<ConnectionItem>`
 
@@ -2311,16 +2311,16 @@ Find a unique connection matching the criteria
 
 **Parameters:**
 
-| Name                | Type      | Required | Default | Possible Values | Description                                                                                                                                         |
-| ------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`           | `object`  | ✅       | —       | —               |                                                                                                                                                     |
-| ​ ↳ `search`        | `string`  | ❌       | —       | —               | Search term to filter connections by title                                                                                                          |
-| ​ ↳ `title`         | `string`  | ❌       | —       | —               | Filter connections by exact title match (searches first, then filters locally)                                                                      |
-| ​ ↳ `owner`         | `string`  | ❌       | —       | —               | Filter by owner, 'me' for your own connections or a specific user ID                                                                                |
-| ​ ↳ `app`           | `string`  | ❌       | —       | —               | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github')                                                                          |
-| ​ ↳ `account`       | `string`  | ❌       | —       | —               | Account to filter by                                                                                                                                |
-| ​ ↳ `includeShared` | `boolean` | ❌       | —       | —               | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
-| ​ ↳ `expired`       | `boolean` | ❌       | —       | —               | Show only expired connections (default: only non-expired connections are returned)                                                                  |
+| Name                | Type      | Required | Default | Possible Values            | Description                                                                                                                                         |
+| ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`           | `object`  | ✅       | —       | —                          |                                                                                                                                                     |
+| ​ ↳ `search`        | `string`  | ❌       | —       | —                          | Search term to filter connections by title                                                                                                          |
+| ​ ↳ `title`         | `string`  | ❌       | —       | —                          | Filter connections by exact title match (searches first, then filters locally)                                                                      |
+| ​ ↳ `owner`         | `string`  | ❌       | —       | —                          | Filter by owner, 'me' for your own connections or a specific user ID                                                                                |
+| ​ ↳ `app`           | `string`  | ❌       | —       | —                          | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github')                                                                          |
+| ​ ↳ `account`       | `string`  | ❌       | —       | —                          | Account to filter by                                                                                                                                |
+| ​ ↳ `includeShared` | `boolean` | ❌       | —       | —                          | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
+| ​ ↳ `status`        | `string`  | ❌       | —       | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both.         |
 
 **Returns:** `Promise<ConnectionItem>`
 
@@ -2462,20 +2462,20 @@ List available connections with optional filtering
 
 **Parameters:**
 
-| Name                | Type      | Required | Default | Possible Values | Description                                                                                                                                         |
-| ------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`           | `object`  | ✅       | —       | —               |                                                                                                                                                     |
-| ​ ↳ `search`        | `string`  | ❌       | —       | —               | Search term to filter connections by title                                                                                                          |
-| ​ ↳ `title`         | `string`  | ❌       | —       | —               | Filter connections by exact title match (searches first, then filters locally)                                                                      |
-| ​ ↳ `owner`         | `string`  | ❌       | —       | —               | Filter by owner, 'me' for your own connections or a specific user ID                                                                                |
-| ​ ↳ `app`           | `string`  | ❌       | —       | —               | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github')                                                                          |
-| ​ ↳ `connections`   | `array`   | ❌       | —       | —               | List of connection IDs to filter by                                                                                                                 |
-| ​ ↳ `account`       | `string`  | ❌       | —       | —               | Account to filter by                                                                                                                                |
-| ​ ↳ `includeShared` | `boolean` | ❌       | —       | —               | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
-| ​ ↳ `expired`       | `boolean` | ❌       | —       | —               | Show only expired connections (default: only non-expired connections are returned)                                                                  |
-| ​ ↳ `pageSize`      | `number`  | ❌       | —       | —               | Number of connections per page                                                                                                                      |
-| ​ ↳ `maxItems`      | `number`  | ❌       | —       | —               | Maximum total items to return across all pages                                                                                                      |
-| ​ ↳ `cursor`        | `string`  | ❌       | —       | —               | Cursor to start from                                                                                                                                |
+| Name                | Type      | Required | Default | Possible Values            | Description                                                                                                                                         |
+| ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`           | `object`  | ✅       | —       | —                          |                                                                                                                                                     |
+| ​ ↳ `search`        | `string`  | ❌       | —       | —                          | Search term to filter connections by title                                                                                                          |
+| ​ ↳ `title`         | `string`  | ❌       | —       | —                          | Filter connections by exact title match (searches first, then filters locally)                                                                      |
+| ​ ↳ `owner`         | `string`  | ❌       | —       | —                          | Filter by owner, 'me' for your own connections or a specific user ID                                                                                |
+| ​ ↳ `app`           | `string`  | ❌       | —       | —                          | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github')                                                                          |
+| ​ ↳ `connections`   | `array`   | ❌       | —       | —                          | List of connection IDs to filter by                                                                                                                 |
+| ​ ↳ `account`       | `string`  | ❌       | —       | —                          | Account to filter by                                                                                                                                |
+| ​ ↳ `includeShared` | `boolean` | ❌       | —       | —                          | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
+| ​ ↳ `status`        | `string`  | ❌       | —       | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both.         |
+| ​ ↳ `pageSize`      | `number`  | ❌       | —       | —                          | Number of connections per page                                                                                                                      |
+| ​ ↳ `maxItems`      | `number`  | ❌       | —       | —                          | Maximum total items to return across all pages                                                                                                      |
+| ​ ↳ `cursor`        | `string`  | ❌       | —       | —                          | Cursor to start from                                                                                                                                |
 
 **Returns:** `Promise<PaginatedResult<ConnectionItem>>`
 

package/dist/{chunk-RTT7PDNL.mjs → chunk-UJLLXQ3L.mjs}

@@ -66,6 +66,13 @@ function getNegatable(schema) {
 function openEnum(values, description) {
   return z.union([z.enum(values), 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);
@@ -109,6 +116,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,
@@ -124,7 +132,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,
@@ -209,6 +221,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",
@@ -620,6 +646,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];
@@ -666,6 +705,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);
@@ -679,7 +730,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) {
@@ -687,6 +738,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();
@@ -753,12 +805,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();
@@ -864,7 +925,8 @@ function createPaginatedFunction(coreFn, options) {
     adaptPage,
     annotator,
     finalizePage,
-    getDeprecation
+    getDeprecation,
+    getStability
   } = options;
   const pageFunction = createPageFunction(coreFn, {
     sdk,
@@ -878,6 +940,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();
@@ -1316,6 +1379,7 @@ var LEAF_META_KEYS = [
   "returnType",
   "outputSchema",
   "packages",
+  "stability",
   "experimental",
   "confirm",
   "deprecation",
@@ -2541,7 +2605,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") {
@@ -2553,7 +2618,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 {
@@ -2567,8 +2633,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
         }
       );
     }
@@ -6512,7 +6580,7 @@ function parseDeprecationDate(value) {
 }
 
 // src/sdk-version.ts
-var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.97.0" : void 0) || "unknown";
+var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.98.0" : void 0) || "unknown";
 
 // src/utils/open-url.ts
 var nodePrefix = "node:";
@@ -6909,11 +6977,16 @@ var ZapierApiClient = class {
         if (!approvalContext) {
           return { response };
         }
+        const askStatementIdsHeader = response.headers.get(
+          "x-zapier-ask-statement-ids"
+        );
+        const askStatementIds = askStatementIdsHeader ? JSON.parse(askStatementIdsHeader) : void 0;
         try {
           await this.runOneApprovalRound(
             approvalContext,
             approvalMode,
-            init?.signal ?? void 0
+            init?.signal ?? void 0,
+            askStatementIds
           );
         } catch (error) {
           return { response, approvalRoundError: error };
@@ -7516,7 +7589,7 @@ var ZapierApiClient = class {
    * Caller is responsible for passing a non-"disabled" mode; this method
    * unconditionally creates an approval.
    */
-  async runOneApprovalRound(buildContext, mode, signal) {
+  async runOneApprovalRound(buildContext, mode, signal, askStatementIds) {
     const context = buildContext();
     let approvalResponse;
     try {
@@ -7526,7 +7599,10 @@ var ZapierApiClient = class {
           "Content-Type": "application/json",
           Accept: "application/json"
         },
-        body: JSON.stringify({ context }),
+        body: JSON.stringify({
+          context,
+          ...askStatementIds?.length ? { ask_statement_ids: askStatementIds } : {}
+        }),
         signal
       });
     } catch (err) {
@@ -11854,14 +11930,24 @@ var ListConnectionsQuerySchema = ListConnectionsQuerySchema$1.omit({
   includeShared: 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: 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: 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: 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: z.number().min(1).optional().describe("Number of connections per page"),
   // SDK specific property for pagination/iterable helpers
@@ -11987,10 +12073,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;