@zuplo/runtime 6.71.20 → 6.71.21

package/out/types/index.d.ts

@@ -3357,6 +3357,19 @@ declare const EventType: {
 
 declare type EventType = (typeof EventType)[keyof typeof EventType];
 
+/**
+ * Parse a response body and extract its GraphQL `errors[]`, including
+ * across an Apollo-style batched (array) response.
+ *
+ * Returns `null` when the body isn't a GraphQL response shape at all
+ * (unparseable JSON, or a JSON scalar), and `[]` for a well-formed
+ * response with no errors — callers treat both as "nothing to report"
+ * but the distinction keeps the function testable.
+ */
+export declare function extractGraphqlErrors(
+  bodyText: string
+): GraphqlResponseError[] | null;
+
 declare interface FetchOptions<T> {
   method?: HttpMethod_2;
   data?: T;
@@ -3596,8 +3609,11 @@ export declare class GoogleCloudLoggingPlugin extends LogPlugin {
  * `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be
  * mapped with `errorCodeClassification`, and anything unrecognized falls
  * back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to
- * also write a structured warning per errored response. Bodies larger
- * than `maxResponseBytes` (default 5 MiB) are not inspected.
+ * also write a structured warning per errored response. The policy reads
+ * up to `maxScanBytes` of the body (128 KiB by default, 5 MiB maximum),
+ * scanning it for the `errors` token; a response larger than that is
+ * treated as error-free. When the token is found and the body fits, it is
+ * parsed and its errors reported.
  *
  * The response always passes through unchanged — the body is read from a
  * clone, and any internal failure is swallowed so reporting can never
@@ -3638,9 +3654,23 @@ export declare interface GraphqlAnalyticsOutboundPolicyOptions {
    */
   logErrors?: boolean;
   /**
-   * Maximum response body size in bytes the policy will inspect. Larger bodies — by `Content-Length`, or measured while reading when the header is absent — pass through without being scanned, so their GraphQL errors (if any) go unreported. The default is 5 MiB.
+   * How many bytes of the response body the policy reads to look for GraphQL errors. The body is read and scanned for the `errors` token up to this limit; a body larger than the limit — by `Content-Length`, or measured while reading when the header is absent — is treated as error-free, so any errors it carries go unreported. The default of 128 KiB suits the common case, where servers emit `errors` near the front of the body. Raise it (up to the 5 MiB maximum) to detect errors in larger responses, at the cost of reading more of every response. When the token is found and the body fits within the limit, the body is parsed and its errors are reported.
    */
-  maxResponseBytes?: number;
+  maxScanBytes?: number;
+}
+
+/**
+ * One GraphQL error extracted from a response body, reduced to the
+ * fields the GraphQL Analytics outbound policy consumes for
+ * classification and (opt-in) logging.
+ */
+export declare interface GraphqlResponseError {
+  /** The error's `message`, or `""` when missing/non-string. */
+  message: string;
+  /** The error's `extensions.code`, or `null` when absent. */
+  code: string | null;
+  /** The error's `path` joined with `.` (e.g. `user.posts.0.title`), or `null`. */
+  path: string | null;
 }
 
 /**
@@ -10126,6 +10156,37 @@ declare type ResolveRequestQuery<
 declare type ResolveUserData<TUserData extends UserDataDefault | undefined> =
   TUserData extends UserDataDefault ? TUserData : UserDataDefault;
 
+/**
+ * Reports whether a `Response` carries GraphQL errors — a `200 OK` with a
+ * top-level `errors[]` array, as Apollo / graphql-yoga servers return on a
+ * failed operation. Reads the body from a clone, so the original response
+ * stream still flows to the client untouched.
+ *
+ * The result is cached against the `response` object: the body is read,
+ * scanned, and parsed at most once per response, and every later call
+ * (including concurrent ones) resolves to the same cached boolean without
+ * touching the stream again.
+ *
+ * Detection reads at most `maxScanBytes` of the body, scanning it for the
+ * `errors` token; a response larger than that — whether by declared
+ * `Content-Length` or as measured while reading — is treated as error-free
+ * and resolves to `false`. Non-JSON responses also resolve to `false`
+ * without reading. Any internal failure is swallowed and reported as
+ * `false` — detection is best-effort and never throws.
+ *
+ * @param response - The response to inspect; left unconsumed.
+ * @param maxScanBytes - How many bytes of the body to read and scan.
+ *   Defaults to {@link DEFAULT_GRAPHQL_SCAN_BYTES} (128 KiB); a body larger
+ *   than this goes unreported. Only the first call for a given `response`
+ *   observes this value; later calls return the cached result.
+ * @returns `true` when the body contains a top-level `errors[]` with at
+ *   least one entry, otherwise `false`.
+ */
+export declare function responseHasGraphqlErrors(
+  response: Response,
+  maxScanBytes?: number
+): Promise<boolean>;
+
 /**
  * Definition of responses for a route
  * @public

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "6.71.20",
+  "version": "6.71.21",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {