@zapier/connectors-sdk 0.1.0-experimental.13 → 0.1.0-experimental.15

package/dist/index.cjs

@@ -92,12 +92,15 @@ var init_build_zapier_fetch = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ConnectorHttpError: () => ConnectorHttpError,
   defineBearerTokenResolver: () => defineBearerTokenResolver,
   defineConnectionResolver: () => defineConnectionResolver,
   defineConnector: () => defineConnector,
   defineTool: () => defineTool,
   handleIfScriptMain: () => handleIfScriptMain,
+  isConnectorHttpError: () => isConnectorHttpError,
   runDispatchCli: () => runDispatchCli,
+  throwForStatus: () => throwForStatus,
   toFunctions: () => toFunctions,
   zapierConnectionResolver: () => zapierConnectionResolver
 });
@@ -702,6 +705,143 @@ function defineTool(config) {
   return base;
 }
 
+// src/errors.ts
+var CONNECTOR_HTTP_ERROR_SYMBOL = /* @__PURE__ */ Symbol.for("connectors.http-error");
+var ConnectorHttpError = class _ConnectorHttpError extends Error {
+  [CONNECTOR_HTTP_ERROR_SYMBOL] = true;
+  name = "ConnectorHttpError";
+  response;
+  constructor(message, options) {
+    super(message);
+    this.response = options.response;
+    Object.setPrototypeOf(this, new.target.prototype);
+    captureOriginStack(this, _ConnectorHttpError);
+  }
+  /**
+   * Multi-line, human-readable rendering for CLI/executable consumption. The
+   * single-line `.message` stays the summary; this adds the connector call site
+   * it was thrown from (the first stack frame, SDK frames elided), the HTTP
+   * `status` (always — so the message never has to restate it), the response
+   * headers (verbatim — they carry header-only signals like `Retry-After`), and
+   * the response body, so an operator (or agent) sees the full picture without
+   * digging into properties. A parsed JSON body is pretty-printed in full
+   * (error payloads are small); a non-JSON text body (HTML pages, stack dumps)
+   * is truncated.
+   */
+  toString() {
+    return formatConnectorHttpError(this);
+  }
+  /**
+   * Build a `ConnectorHttpError` from a `Response` whose body has already been
+   * read. This is the control path: a connector that wants its own message, or
+   * whose failure arrives as `200 { ok: false }` (so the body is read before
+   * the error is known), calls this directly. When `message` is omitted, a
+   * generic `HTTP <status> <statusText>` summary is used.
+   */
+  static fromResponseBody(res, body, opts = {}) {
+    const headers = res.headers;
+    const statusText = res.statusText ? ` ${res.statusText}` : "";
+    const err = new _ConnectorHttpError(
+      opts.message ?? `HTTP ${res.status}${statusText}`,
+      {
+        response: {
+          status: res.status,
+          statusText: res.statusText ?? "",
+          headers: headers ? headersToRecord(headers) : {},
+          body
+        }
+      }
+    );
+    captureOriginStack(err, _ConnectorHttpError.fromResponseBody);
+    return err;
+  }
+};
+function isConnectorHttpError(value) {
+  return Boolean(
+    value && typeof value === "object" && value[CONNECTOR_HTTP_ERROR_SYMBOL] === true
+  );
+}
+async function throwForStatus(res, message) {
+  if (res.ok) return res;
+  const origin = {};
+  captureOriginStack(origin, throwForStatus);
+  const err = ConnectorHttpError.fromResponseBody(res, await readBody(res), {
+    message
+  });
+  const firstNewline = origin.stack?.indexOf("\n") ?? -1;
+  if (origin.stack !== void 0 && firstNewline !== -1) {
+    err.stack = `${err.name}: ${err.message}${origin.stack.slice(firstNewline)}`;
+  }
+  throw err;
+}
+function captureOriginStack(target, sentinel) {
+  const capture = Error.captureStackTrace;
+  if (typeof capture === "function") capture(target, sentinel);
+}
+function headersToRecord(headers) {
+  const out = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+async function readBody(res) {
+  let text;
+  try {
+    text = await res.text();
+  } catch {
+    return void 0;
+  }
+  if (text === "") return "";
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var MAX_BODY_CHARS = 2e3;
+function formatConnectorHttpError(err) {
+  const lines = [`${err.name}: ${err.message}`];
+  const origin = originFrame(err.stack);
+  if (origin) lines.push(`  ${origin}`);
+  const { status, statusText } = err.response;
+  lines.push(`  status: ${status}${statusText ? ` ${statusText}` : ""}`);
+  const headers = formatHeaders(err.response.headers);
+  if (headers) lines.push(headers);
+  if (err.response.body !== void 0 && err.response.body !== "") {
+    lines.push(`  body: ${summarizeBody(err.response.body)}`);
+  }
+  return lines.join("\n");
+}
+function formatHeaders(headers) {
+  const entries = Object.entries(headers);
+  if (entries.length === 0) return void 0;
+  const rendered = entries.map(([key, value]) => `    ${key}: ${value}`);
+  return `  headers:
+${rendered.join("\n")}`;
+}
+function originFrame(stack) {
+  if (!stack) return void 0;
+  for (const line of stack.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("at ")) return trimmed;
+  }
+  return void 0;
+}
+function summarizeBody(body) {
+  if (typeof body === "string") {
+    return body.length > MAX_BODY_CHARS ? `${body.slice(0, MAX_BODY_CHARS)}\u2026 (truncated)` : body;
+  }
+  return safeJsonStringify(body) ?? String(body);
+}
+function safeJsonStringify(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return void 0;
+  }
+}
+
 // src/surfaces/handle-if-script-main.ts
 var import_zod3 = require("zod");
 
@@ -823,11 +963,31 @@ async function buildMcpServer(meta, connector, opts = {}) {
       // `input` because the registry walk is polymorphic over every
       // script's schema.
       async (input) => {
-        const result = await script.run(input, runOpts);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: result
-        };
+        try {
+          const result = await script.run(input, runOpts);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result
+          };
+        } catch (err) {
+          if (isConnectorHttpError(err)) {
+            return {
+              content: [
+                { type: "text", text: err.toString() },
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    { message: err.message, response: err.response },
+                    null,
+                    2
+                  )
+                }
+              ],
+              isError: true
+            };
+          }
+          throw err;
+        }
       }
     );
   }
@@ -915,7 +1075,7 @@ async function runDispatchCli(meta, connector) {
   }
 }
 function reportFatalErrorAndExit(err, stderr, exit) {
-  const message = err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : String(err);
+  const message = isConnectorHttpError(err) ? err.toString() : err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : String(err);
   stderr.write(`${message}
 `);
   exit(1);
@@ -1164,18 +1324,14 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
     } else if (arg === "--filter") {
       const value = args[i + 1];
       if (value === void 0 || value.length === 0) {
-        throw new Error(
-          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
-        );
+        throw new Error(`\`--filter\` requires a jq expression argument.`);
       }
       filter = value;
       i++;
     } else if (arg.startsWith("--filter=")) {
       const value = arg.slice("--filter=".length);
       if (value.length === 0) {
-        throw new Error(
-          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
-        );
+        throw new Error(`\`--filter\` requires a jq expression argument.`);
       }
       filter = value;
     } else if (arg.startsWith("--")) {
@@ -1257,10 +1413,11 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   lines.push("");
   lines.push(
-    "  --filter <jq>  Transform the JSON output through a jq expression."
+    "  --filter <jq>  Transform the JSON output through a jq expression,"
+  );
+  lines.push(
+    "                 e.g. to trim large results. See the output schema below."
   );
-  lines.push("                 Useful for trimming large outputs, e.g.");
-  lines.push("                 --filter '.results | length'.");
   lines.push("");
   if (opts.invocation) {
     lines.push("Example:");
@@ -1353,12 +1510,15 @@ function toFunctions(connector) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ConnectorHttpError,
   defineBearerTokenResolver,
   defineConnectionResolver,
   defineConnector,
   defineTool,
   handleIfScriptMain,
+  isConnectorHttpError,
   runDispatchCli,
+  throwForStatus,
   toFunctions,
   zapierConnectionResolver
 });

package/dist/index.d.cts

@@ -453,6 +453,116 @@ declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends
 declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TName, TKey>;
 declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TName, TSlots, TKey>;
 
+/**
+ * `ConnectorHttpError` — the standardized error every connector throws on a
+ * failed API response, plus the `throwForStatus` helper that builds it.
+ *
+ * Goal (STAFF-4049): give agents and CLI consumers full, transparent context
+ * about a failed HTTP call by carrying the response that came back (status,
+ * headers, parsed body) — instead of a lossy `throw new Error(\`X 400:
+ * ${body}\`)` per connector. Everything agent-actionable an API surfaces
+ * (machine error codes like `missing_scope`, `Retry-After`, etc.) is already
+ * in `response.body` / `response.headers`; we don't promote derived fields off
+ * the response. Callers read what they need from `error.response`.
+ *
+ * We deliberately do NOT pull in kitcore's `adaptError` factory: that
+ * indirection exists to map kitcore's internal throws onto a head SDK's
+ * branded class across a plugin boundary; here we own both the throw site and
+ * the class.
+ *
+ * Two construction paths:
+ *   - `throwForStatus(res, message?)` — reads the failed body for you and
+ *     throws. The 90% case. The optional `message` names the call site (e.g.
+ *     "Failed to read the source page"); the status never needs to be in it,
+ *     since `toString()` always renders the `status: <code> <text>` line.
+ *   - `ConnectorHttpError.fromResponseBody(res, body, { message? })` — for when
+ *     the body is already in hand: a failure that arrives as `200 { ok: false }`
+ *     (body read before the error is known), or a caller shaping the response
+ *     itself.
+ *
+ * Recognition is brand-based (`Symbol.for` + `isConnectorHttpError`), not
+ * `instanceof`: `apps/*` connectors bundle the SDK standalone, so multiple
+ * copies of this module can coexist in one process and `instanceof` would miss
+ * cross-copy instances.
+ */
+/** The response as it came back. `body` is parsed JSON when possible, else text. */
+interface ConnectorHttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+interface ConnectorHttpErrorOptions {
+    response: ConnectorHttpResponse;
+}
+/**
+ * Cross-realm/cross-bundle brand. `Symbol.for` reads the engine-global
+ * registry, so the same value resolves across multiple copies of this module
+ * (one bundled into each `apps/*` connector). Use `isConnectorHttpError` for
+ * recognition rather than `instanceof`.
+ */
+declare const CONNECTOR_HTTP_ERROR_SYMBOL: unique symbol;
+declare class ConnectorHttpError extends Error {
+    readonly [CONNECTOR_HTTP_ERROR_SYMBOL] = true;
+    readonly name = "ConnectorHttpError";
+    readonly response: ConnectorHttpResponse;
+    constructor(message: string, options: ConnectorHttpErrorOptions);
+    /**
+     * Multi-line, human-readable rendering for CLI/executable consumption. The
+     * single-line `.message` stays the summary; this adds the connector call site
+     * it was thrown from (the first stack frame, SDK frames elided), the HTTP
+     * `status` (always — so the message never has to restate it), the response
+     * headers (verbatim — they carry header-only signals like `Retry-After`), and
+     * the response body, so an operator (or agent) sees the full picture without
+     * digging into properties. A parsed JSON body is pretty-printed in full
+     * (error payloads are small); a non-JSON text body (HTML pages, stack dumps)
+     * is truncated.
+     */
+    toString(): string;
+    /**
+     * Build a `ConnectorHttpError` from a `Response` whose body has already been
+     * read. This is the control path: a connector that wants its own message, or
+     * whose failure arrives as `200 { ok: false }` (so the body is read before
+     * the error is known), calls this directly. When `message` is omitted, a
+     * generic `HTTP <status> <statusText>` summary is used.
+     */
+    static fromResponseBody(res: Pick<Response, "status" | "statusText" | "headers">, body: unknown, opts?: {
+        message?: string;
+    }): ConnectorHttpError;
+}
+/** Cross-bundle-safe recognizer. Prefer this over `instanceof`. */
+declare function isConnectorHttpError(value: unknown): value is ConnectorHttpError;
+/**
+ * Throw a `ConnectorHttpError` when `res` is not ok; otherwise return `res`
+ * unchanged (the success-path body is never consumed, so callers can still
+ * read it). A delegator: it reads the failed body and hands off to
+ * `ConnectorHttpError.fromResponseBody`. Named after the `zapier-platform`
+ * CLI's `response.throwForStatus()` idiom, but a standalone helper — it does
+ * not augment the `Response`.
+ *
+ * For the common path:
+ *
+ *   const res = await ctx.fetch(url, init);
+ *   await throwForStatus(res);
+ *   return res.json();
+ *
+ * The optional `message` describes the call site for the rendered error and
+ * the thrown `.message` — useful when one script makes several requests and a
+ * bare `HTTP 404` wouldn't say which:
+ *
+ *   await throwForStatus(readRes, "Failed to read the source page");
+ *   await throwForStatus(createRes, "Failed to create the target page");
+ *
+ * The `message` need not mention the status: `toString()` always renders a
+ * `status: <code> <text>` line. When omitted, a generic `HTTP <status>
+ * <statusText>` summary is used.
+ *
+ * When the failure arrives in a 200 body (so the body must be read before the
+ * error is known), build the error directly with
+ * `ConnectorHttpError.fromResponseBody(res, body, { message? })` instead.
+ */
+declare function throwForStatus(res: Response, message?: string): Promise<Response>;
+
 /**
  * `handleIfScriptMain(meta, definition, opts?)` — per-script CLI execution
  * surface (not the connector bin).
@@ -570,4 +680,4 @@ type NamedFunctions<TScripts extends AnyScripts> = {
  */
 declare function toFunctions<TScripts extends AnyScripts, TResolvers extends ConnectionResolversMap>(connector: ConnectorDefinition<TScripts, TResolvers>): NamedFunctions<ConnectorDefinition<TScripts, TResolvers>["scripts"]>;
 
-export { type AnyToolDefinition, type ConnectorDefinition, type RunOptions, defineBearerTokenResolver, defineConnectionResolver, defineConnector, defineTool, handleIfScriptMain, runDispatchCli, toFunctions, zapierConnectionResolver };
+export { type AnyToolDefinition, type ConnectorDefinition, ConnectorHttpError, type ConnectorHttpErrorOptions, type ConnectorHttpResponse, type RunOptions, defineBearerTokenResolver, defineConnectionResolver, defineConnector, defineTool, handleIfScriptMain, isConnectorHttpError, runDispatchCli, throwForStatus, toFunctions, zapierConnectionResolver };

package/dist/index.d.ts

@@ -453,6 +453,116 @@ declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends
 declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TName, TKey>;
 declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TName, TSlots, TKey>;
 
+/**
+ * `ConnectorHttpError` — the standardized error every connector throws on a
+ * failed API response, plus the `throwForStatus` helper that builds it.
+ *
+ * Goal (STAFF-4049): give agents and CLI consumers full, transparent context
+ * about a failed HTTP call by carrying the response that came back (status,
+ * headers, parsed body) — instead of a lossy `throw new Error(\`X 400:
+ * ${body}\`)` per connector. Everything agent-actionable an API surfaces
+ * (machine error codes like `missing_scope`, `Retry-After`, etc.) is already
+ * in `response.body` / `response.headers`; we don't promote derived fields off
+ * the response. Callers read what they need from `error.response`.
+ *
+ * We deliberately do NOT pull in kitcore's `adaptError` factory: that
+ * indirection exists to map kitcore's internal throws onto a head SDK's
+ * branded class across a plugin boundary; here we own both the throw site and
+ * the class.
+ *
+ * Two construction paths:
+ *   - `throwForStatus(res, message?)` — reads the failed body for you and
+ *     throws. The 90% case. The optional `message` names the call site (e.g.
+ *     "Failed to read the source page"); the status never needs to be in it,
+ *     since `toString()` always renders the `status: <code> <text>` line.
+ *   - `ConnectorHttpError.fromResponseBody(res, body, { message? })` — for when
+ *     the body is already in hand: a failure that arrives as `200 { ok: false }`
+ *     (body read before the error is known), or a caller shaping the response
+ *     itself.
+ *
+ * Recognition is brand-based (`Symbol.for` + `isConnectorHttpError`), not
+ * `instanceof`: `apps/*` connectors bundle the SDK standalone, so multiple
+ * copies of this module can coexist in one process and `instanceof` would miss
+ * cross-copy instances.
+ */
+/** The response as it came back. `body` is parsed JSON when possible, else text. */
+interface ConnectorHttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+interface ConnectorHttpErrorOptions {
+    response: ConnectorHttpResponse;
+}
+/**
+ * Cross-realm/cross-bundle brand. `Symbol.for` reads the engine-global
+ * registry, so the same value resolves across multiple copies of this module
+ * (one bundled into each `apps/*` connector). Use `isConnectorHttpError` for
+ * recognition rather than `instanceof`.
+ */
+declare const CONNECTOR_HTTP_ERROR_SYMBOL: unique symbol;
+declare class ConnectorHttpError extends Error {
+    readonly [CONNECTOR_HTTP_ERROR_SYMBOL] = true;
+    readonly name = "ConnectorHttpError";
+    readonly response: ConnectorHttpResponse;
+    constructor(message: string, options: ConnectorHttpErrorOptions);
+    /**
+     * Multi-line, human-readable rendering for CLI/executable consumption. The
+     * single-line `.message` stays the summary; this adds the connector call site
+     * it was thrown from (the first stack frame, SDK frames elided), the HTTP
+     * `status` (always — so the message never has to restate it), the response
+     * headers (verbatim — they carry header-only signals like `Retry-After`), and
+     * the response body, so an operator (or agent) sees the full picture without
+     * digging into properties. A parsed JSON body is pretty-printed in full
+     * (error payloads are small); a non-JSON text body (HTML pages, stack dumps)
+     * is truncated.
+     */
+    toString(): string;
+    /**
+     * Build a `ConnectorHttpError` from a `Response` whose body has already been
+     * read. This is the control path: a connector that wants its own message, or
+     * whose failure arrives as `200 { ok: false }` (so the body is read before
+     * the error is known), calls this directly. When `message` is omitted, a
+     * generic `HTTP <status> <statusText>` summary is used.
+     */
+    static fromResponseBody(res: Pick<Response, "status" | "statusText" | "headers">, body: unknown, opts?: {
+        message?: string;
+    }): ConnectorHttpError;
+}
+/** Cross-bundle-safe recognizer. Prefer this over `instanceof`. */
+declare function isConnectorHttpError(value: unknown): value is ConnectorHttpError;
+/**
+ * Throw a `ConnectorHttpError` when `res` is not ok; otherwise return `res`
+ * unchanged (the success-path body is never consumed, so callers can still
+ * read it). A delegator: it reads the failed body and hands off to
+ * `ConnectorHttpError.fromResponseBody`. Named after the `zapier-platform`
+ * CLI's `response.throwForStatus()` idiom, but a standalone helper — it does
+ * not augment the `Response`.
+ *
+ * For the common path:
+ *
+ *   const res = await ctx.fetch(url, init);
+ *   await throwForStatus(res);
+ *   return res.json();
+ *
+ * The optional `message` describes the call site for the rendered error and
+ * the thrown `.message` — useful when one script makes several requests and a
+ * bare `HTTP 404` wouldn't say which:
+ *
+ *   await throwForStatus(readRes, "Failed to read the source page");
+ *   await throwForStatus(createRes, "Failed to create the target page");
+ *
+ * The `message` need not mention the status: `toString()` always renders a
+ * `status: <code> <text>` line. When omitted, a generic `HTTP <status>
+ * <statusText>` summary is used.
+ *
+ * When the failure arrives in a 200 body (so the body must be read before the
+ * error is known), build the error directly with
+ * `ConnectorHttpError.fromResponseBody(res, body, { message? })` instead.
+ */
+declare function throwForStatus(res: Response, message?: string): Promise<Response>;
+
 /**
  * `handleIfScriptMain(meta, definition, opts?)` — per-script CLI execution
  * surface (not the connector bin).
@@ -570,4 +680,4 @@ type NamedFunctions<TScripts extends AnyScripts> = {
  */
 declare function toFunctions<TScripts extends AnyScripts, TResolvers extends ConnectionResolversMap>(connector: ConnectorDefinition<TScripts, TResolvers>): NamedFunctions<ConnectorDefinition<TScripts, TResolvers>["scripts"]>;
 
-export { type AnyToolDefinition, type ConnectorDefinition, type RunOptions, defineBearerTokenResolver, defineConnectionResolver, defineConnector, defineTool, handleIfScriptMain, runDispatchCli, toFunctions, zapierConnectionResolver };
+export { type AnyToolDefinition, type ConnectorDefinition, ConnectorHttpError, type ConnectorHttpErrorOptions, type ConnectorHttpResponse, type RunOptions, defineBearerTokenResolver, defineConnectionResolver, defineConnector, defineTool, handleIfScriptMain, isConnectorHttpError, runDispatchCli, throwForStatus, toFunctions, zapierConnectionResolver };

package/dist/index.js

@@ -596,6 +596,143 @@ function defineTool(config) {
   return base;
 }
 
+// src/errors.ts
+var CONNECTOR_HTTP_ERROR_SYMBOL = /* @__PURE__ */ Symbol.for("connectors.http-error");
+var ConnectorHttpError = class _ConnectorHttpError extends Error {
+  [CONNECTOR_HTTP_ERROR_SYMBOL] = true;
+  name = "ConnectorHttpError";
+  response;
+  constructor(message, options) {
+    super(message);
+    this.response = options.response;
+    Object.setPrototypeOf(this, new.target.prototype);
+    captureOriginStack(this, _ConnectorHttpError);
+  }
+  /**
+   * Multi-line, human-readable rendering for CLI/executable consumption. The
+   * single-line `.message` stays the summary; this adds the connector call site
+   * it was thrown from (the first stack frame, SDK frames elided), the HTTP
+   * `status` (always — so the message never has to restate it), the response
+   * headers (verbatim — they carry header-only signals like `Retry-After`), and
+   * the response body, so an operator (or agent) sees the full picture without
+   * digging into properties. A parsed JSON body is pretty-printed in full
+   * (error payloads are small); a non-JSON text body (HTML pages, stack dumps)
+   * is truncated.
+   */
+  toString() {
+    return formatConnectorHttpError(this);
+  }
+  /**
+   * Build a `ConnectorHttpError` from a `Response` whose body has already been
+   * read. This is the control path: a connector that wants its own message, or
+   * whose failure arrives as `200 { ok: false }` (so the body is read before
+   * the error is known), calls this directly. When `message` is omitted, a
+   * generic `HTTP <status> <statusText>` summary is used.
+   */
+  static fromResponseBody(res, body, opts = {}) {
+    const headers = res.headers;
+    const statusText = res.statusText ? ` ${res.statusText}` : "";
+    const err = new _ConnectorHttpError(
+      opts.message ?? `HTTP ${res.status}${statusText}`,
+      {
+        response: {
+          status: res.status,
+          statusText: res.statusText ?? "",
+          headers: headers ? headersToRecord(headers) : {},
+          body
+        }
+      }
+    );
+    captureOriginStack(err, _ConnectorHttpError.fromResponseBody);
+    return err;
+  }
+};
+function isConnectorHttpError(value) {
+  return Boolean(
+    value && typeof value === "object" && value[CONNECTOR_HTTP_ERROR_SYMBOL] === true
+  );
+}
+async function throwForStatus(res, message) {
+  if (res.ok) return res;
+  const origin = {};
+  captureOriginStack(origin, throwForStatus);
+  const err = ConnectorHttpError.fromResponseBody(res, await readBody(res), {
+    message
+  });
+  const firstNewline = origin.stack?.indexOf("\n") ?? -1;
+  if (origin.stack !== void 0 && firstNewline !== -1) {
+    err.stack = `${err.name}: ${err.message}${origin.stack.slice(firstNewline)}`;
+  }
+  throw err;
+}
+function captureOriginStack(target, sentinel) {
+  const capture = Error.captureStackTrace;
+  if (typeof capture === "function") capture(target, sentinel);
+}
+function headersToRecord(headers) {
+  const out = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+async function readBody(res) {
+  let text;
+  try {
+    text = await res.text();
+  } catch {
+    return void 0;
+  }
+  if (text === "") return "";
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var MAX_BODY_CHARS = 2e3;
+function formatConnectorHttpError(err) {
+  const lines = [`${err.name}: ${err.message}`];
+  const origin = originFrame(err.stack);
+  if (origin) lines.push(`  ${origin}`);
+  const { status, statusText } = err.response;
+  lines.push(`  status: ${status}${statusText ? ` ${statusText}` : ""}`);
+  const headers = formatHeaders(err.response.headers);
+  if (headers) lines.push(headers);
+  if (err.response.body !== void 0 && err.response.body !== "") {
+    lines.push(`  body: ${summarizeBody(err.response.body)}`);
+  }
+  return lines.join("\n");
+}
+function formatHeaders(headers) {
+  const entries = Object.entries(headers);
+  if (entries.length === 0) return void 0;
+  const rendered = entries.map(([key, value]) => `    ${key}: ${value}`);
+  return `  headers:
+${rendered.join("\n")}`;
+}
+function originFrame(stack) {
+  if (!stack) return void 0;
+  for (const line of stack.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("at ")) return trimmed;
+  }
+  return void 0;
+}
+function summarizeBody(body) {
+  if (typeof body === "string") {
+    return body.length > MAX_BODY_CHARS ? `${body.slice(0, MAX_BODY_CHARS)}\u2026 (truncated)` : body;
+  }
+  return safeJsonStringify(body) ?? String(body);
+}
+function safeJsonStringify(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return void 0;
+  }
+}
+
 // src/surfaces/handle-if-script-main.ts
 import { z as z3 } from "zod";
 
@@ -717,11 +854,31 @@ async function buildMcpServer(meta, connector, opts = {}) {
       // `input` because the registry walk is polymorphic over every
       // script's schema.
       async (input) => {
-        const result = await script.run(input, runOpts);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: result
-        };
+        try {
+          const result = await script.run(input, runOpts);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result
+          };
+        } catch (err) {
+          if (isConnectorHttpError(err)) {
+            return {
+              content: [
+                { type: "text", text: err.toString() },
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    { message: err.message, response: err.response },
+                    null,
+                    2
+                  )
+                }
+              ],
+              isError: true
+            };
+          }
+          throw err;
+        }
       }
     );
   }
@@ -809,7 +966,7 @@ async function runDispatchCli(meta, connector) {
   }
 }
 function reportFatalErrorAndExit(err, stderr, exit) {
-  const message = err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : String(err);
+  const message = isConnectorHttpError(err) ? err.toString() : err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : String(err);
   stderr.write(`${message}
 `);
   exit(1);
@@ -1058,18 +1215,14 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
     } else if (arg === "--filter") {
       const value = args[i + 1];
       if (value === void 0 || value.length === 0) {
-        throw new Error(
-          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
-        );
+        throw new Error(`\`--filter\` requires a jq expression argument.`);
       }
       filter = value;
       i++;
     } else if (arg.startsWith("--filter=")) {
       const value = arg.slice("--filter=".length);
       if (value.length === 0) {
-        throw new Error(
-          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
-        );
+        throw new Error(`\`--filter\` requires a jq expression argument.`);
       }
       filter = value;
     } else if (arg.startsWith("--")) {
@@ -1151,10 +1304,11 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   lines.push("");
   lines.push(
-    "  --filter <jq>  Transform the JSON output through a jq expression."
+    "  --filter <jq>  Transform the JSON output through a jq expression,"
+  );
+  lines.push(
+    "                 e.g. to trim large results. See the output schema below."
   );
-  lines.push("                 Useful for trimming large outputs, e.g.");
-  lines.push("                 --filter '.results | length'.");
   lines.push("");
   if (opts.invocation) {
     lines.push("Example:");
@@ -1246,12 +1400,15 @@ function toFunctions(connector) {
   return out;
 }
 export {
+  ConnectorHttpError,
   defineBearerTokenResolver,
   defineConnectionResolver,
   defineConnector,
   defineTool,
   handleIfScriptMain,
+  isConnectorHttpError,
   runDispatchCli,
+  throwForStatus,
   toFunctions,
   zapierConnectionResolver
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/connectors-sdk",
-  "version": "0.1.0-experimental.13",
+  "version": "0.1.0-experimental.15",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",