stitchkit 0.72.5 → 0.74.0

package/dist/{index-6d32zk83.js → index-58jzmnn4.js}

@@ -72,6 +72,62 @@ function cancellationError(cause) {
   return new RequestCancellationError(cause);
 }
 
+// src/browser/http.ts
+import ky, {
+  isHTTPError,
+  isNetworkError,
+  isTimeoutError
+} from "ky";
+
+// src/browser/request-id.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function responseTraceId(response) {
+  return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
+}
+
+// src/browser/http.ts
+var API_ERROR_BRAND = Symbol.for("stitchkit.ApiError");
+function messageForCode(code, message) {
+  return message !== undefined && message.length > 0 ? message : `${code} (no message supplied)`;
+}
+
+class ApiError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  traceId;
+  constructor(code, status = 0, details, message, hint, traceId, options) {
+    super(messageForCode(code, message), options);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.traceId = traceId;
+    this.name = "ApiError";
+    Object.defineProperty(this, API_ERROR_BRAND, { value: true });
+  }
+  static is(error) {
+    return typeof error === "object" && error !== null && API_ERROR_BRAND in error;
+  }
+}
+function refuseLocally(path, message) {
+  return new ApiError("VALIDATION_ERROR", 0, { issues: [{ path, code: "invalid_type", message }] }, message);
+}
+function parseApiErrorBody(body) {
+  if (!isRecord(body) || !isRecord(body.error))
+    return null;
+  const error = body.error;
+  if (typeof error.code !== "string")
+    return null;
+  return {
+    code: error.code,
+    message: typeof error.message === "string" ? error.message : undefined,
+    details: error.details,
+    hint: typeof error.hint === "string" ? error.hint : undefined
+  };
+}
+
 // src/browser/client-multipart.ts
 function isFileDescriptor(value) {
   return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
@@ -96,24 +152,26 @@ function buildMultipartForm(descriptor, values) {
   for (const [field, policy] of Object.entries(descriptor.files)) {
     const value = values[field];
     if (value === undefined) {
-      if (policy.required !== false)
-        throw new Error(`Missing multipart file field: ${field}`);
+      if (policy.required !== false) {
+        throw refuseLocally(field, `Missing multipart file field: ${field}`);
+      }
       continue;
     }
     if (policy.multiple === true) {
       if (!Array.isArray(value) || value.length === 0) {
-        throw new Error(`Multipart file field "${field}" must be a non-empty array`);
+        throw refuseLocally(field, `Multipart file field "${field}" must be a non-empty array`);
       }
       for (const file of value) {
         if (!isMultipartFile(file)) {
-          throw new Error(`Invalid multipart file field: ${field}`);
+          throw refuseLocally(field, `Invalid multipart file field: ${field}`);
         }
         appendMultipartFile(formData, field, file);
       }
       continue;
     }
-    if (!isMultipartFile(value))
-      throw new Error(`Invalid multipart file field: ${field}`);
+    if (!isMultipartFile(value)) {
+      throw refuseLocally(field, `Invalid multipart file field: ${field}`);
+    }
     appendMultipartFile(formData, field, value);
   }
   appendFormFields(formData, values, fileFields);
@@ -136,7 +194,7 @@ function collectQueryParams(args, endpoint) {
       continue;
     }
     const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
-    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+    throw refuseLocally(key, `${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
   }
   return hasParams ? params : undefined;
 }
@@ -155,7 +213,7 @@ function resolvePathPrefix(config, args) {
   const keys = config.stripPrefixKeys ?? [];
   if (!hasStringKeys(args, keys)) {
     const missing = keys.find((key) => typeof args[key] !== "string");
-    throw new Error(`Missing path prefix key: ${missing}`);
+    throw refuseLocally(String(missing), `Missing path prefix key: ${missing}`);
   }
   return config.pathPrefix(args);
 }
@@ -172,7 +230,7 @@ function fillPathParams(path, args) {
   let filled = path.replace(/:(\w+)/g, (_, key) => {
     const value = args[key];
     if (value === undefined || value === null) {
-      throw new Error(`Missing path param: ${key}`);
+      throw refuseLocally(String(key), `Missing path param: ${key}`);
     }
     return encodeURIComponent(String(value));
   });
@@ -180,7 +238,7 @@ function fillPathParams(path, args) {
     return filled;
   const wildcardValue = args[wildcard.name];
   if (wildcardValue === undefined || wildcardValue === null) {
-    throw new Error(`Missing path param: ${wildcard.name}`);
+    throw refuseLocally(wildcard.name, `Missing path param: ${wildcard.name}`);
   }
   const remainder = String(wildcardValue).split("/").map((segment) => encodeURIComponent(segment)).join("/");
   filled = `${filled.slice(0, -(wildcard.name.length + 1))}${remainder}`;
@@ -232,56 +290,6 @@ function joinClientBaseUrl(baseUrl, relativeUrl) {
   const path = relativeUrl.startsWith("/") ? relativeUrl : `/${relativeUrl}`;
   return `${base}${path}`;
 }
-
-// src/browser/http.ts
-import ky, {
-  isHTTPError,
-  isNetworkError,
-  isTimeoutError
-} from "ky";
-
-// src/browser/request-id.ts
-var REQUEST_ID_HEADER = "x-request-id";
-function responseTraceId(response) {
-  return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
-}
-
-// src/browser/http.ts
-var API_ERROR_BRAND = Symbol.for("stitchkit.ApiError");
-
-class ApiError extends Error {
-  code;
-  status;
-  details;
-  hint;
-  traceId;
-  constructor(code, status = 0, details, message, hint, traceId, options) {
-    super(message ?? `API Error: ${code}`, options);
-    this.code = code;
-    this.status = status;
-    this.details = details;
-    this.hint = hint;
-    this.traceId = traceId;
-    this.name = "ApiError";
-    Object.defineProperty(this, API_ERROR_BRAND, { value: true });
-  }
-  static is(error) {
-    return typeof error === "object" && error !== null && API_ERROR_BRAND in error;
-  }
-}
-function parseApiErrorBody(body) {
-  if (!isRecord(body) || !isRecord(body.error))
-    return null;
-  const error = body.error;
-  if (typeof error.code !== "string")
-    return null;
-  return {
-    code: error.code,
-    message: typeof error.message === "string" ? error.message : undefined,
-    details: error.details,
-    hint: typeof error.hint === "string" ? error.hint : undefined
-  };
-}
 // src/browser/stream.ts
 function parseFailure(raw, error, onParseError) {
   const failure = error instanceof Error ? error : new Error(String(error));
@@ -462,16 +470,35 @@ function setClientMethod(target, key, method) {
 function createEndpointMethod(endpoint, execute, contractConfig) {
   const hasScopedArguments = (contractConfig?.stripPrefixKeys?.length ?? 0) > 0;
   if (endpointHasArguments(endpoint) || hasScopedArguments) {
-    const method2 = (requestArgs) => execute(readClientRequestArgs(requestArgs), undefined);
+    const method2 = (requestArgs) => settle(execute, readClientRequestArgs(requestArgs), undefined);
     return Object.assign(method2, {
-      withOptions: (requestArgs, options) => execute(readClientRequestArgs(requestArgs), readClientRequestOptions(options))
+      withOptions: (...args) => {
+        refuseExtraWithOptionsArguments(endpoint, args.length, 2);
+        return settle(execute, readClientRequestArgs(args[0]), readClientRequestOptions(args[1]));
+      }
     });
   }
-  const method = () => execute({}, undefined);
+  const method = () => settle(execute, {}, undefined);
   return Object.assign(method, {
-    withOptions: (options) => execute({}, readClientRequestOptions(options))
+    withOptions: (...args) => {
+      refuseExtraWithOptionsArguments(endpoint, args.length, 1);
+      return settle(execute, {}, readClientRequestOptions(args[0]));
+    }
   });
 }
+function settle(execute, requestArgs, options) {
+  try {
+    return execute(requestArgs, options);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+function refuseExtraWithOptionsArguments(endpoint, received, expected) {
+  if (received <= expected)
+    return;
+  const shape = expected === 1 ? "withOptions(options)" : "withOptions(args, options)";
+  throw new TypeError(`${endpoint.method} ${endpoint.path}: this endpoint declares ${expected === 1 ? "no input" : "an input"}, so its method is ${shape} — it received ${received} arguments. ` + "An extra argument here is dropped, and a request options object in the dropped position " + "sends the request without them: an abort signal placed there never reaches the server.");
+}
 function createHttpExecutor(endpoint, prefix, client, config) {
   const httpMethod = endpoint.method.toLowerCase();
   return (requestArgs, options) => {

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export type { BindRealtimeClientOptions, BoundRealtimeClient, RealtimeClient, Re
 export { bindRealtimeClient, createRealtimeClient, createSocketIOClient, } from './browser/socket-io.js';
 export { type ParseNDJSONOptions, type ParseSSEOptions, parseNDJSON, parseSSE, } from './browser/stream.js';
 export * from './contract/index.js';
+export { formatZodError, type ZodIssueSummary, zodIssues } from './internal/errors.js';
 export type { StitchLogger } from './logger.js';
 export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, type TraceContext, } from './observability/trace.js';
 export * from './realtime/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,mBAAmB,EACnB,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,WAAW,EACX,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,mBAAmB,EACnB,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,WAAW,EACX,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAC1B,cAAc,YAAY,CAAC;AAK3B,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACpF,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}