@stacksjs/browser 0.70.189 → 0.70.191

package/dist/composables/index.d.ts

@@ -1,4 +1,5 @@
 export * from './csrf';
+export * from './request-error';
 export * from './useAuth';
 export * from './useApi';
 // Re-export browser-relevant composables from @stacksjs/composables

package/dist/composables/index.js

@@ -1,4 +1,5 @@
 export * from "./csrf";
+export * from "./request-error";
 export * from "./useAuth";
 export * from "./useApi";
 export {

package/dist/composables/request-error.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Describe a non-OK HTTP response.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch('/api/login', { method: 'POST', body })
+ * if (!res.ok) {
+ *   const failure = describeResponseError(res.status, await res.json())
+ *   error.set(failure.message)
+ * }
+ * ```
+ */
+export declare function describeResponseError(status: number, body?: ApiErrorBody | null): UserFacingError;
+/**
+ * Describe something thrown while making a request.
+ *
+ * A runtime defect never reaches the returned `message`. That is the whole
+ * point: `auth is not defined` is a bug report, and it belongs in the console,
+ * not in front of the person trying to sign in.
+ *
+ * @example
+ * ```ts
+ * catch (err) {
+ *   const failure = describeThrownError(err)
+ *   if (failure.unexpected)
+ *     console.error('[login]', failure.cause)
+ *   error.set(failure.message)
+ * }
+ * ```
+ */
+export declare function describeThrownError(error: unknown): UserFacingError;
+/**
+ * Turn a failed request, or a thrown exception, into something worth showing
+ * a person.
+ *
+ * The pattern this replaces is `catch (err) { error.set(err.message) }`. It
+ * looks like error handling and is actually a passthrough: whatever the
+ * runtime happened to say lands in the UI. A sign-in form built that way
+ * greeted people with `auth is not defined` - a programmer's ReferenceError,
+ * rendered as if it were advice - and told them nothing about what to do next.
+ *
+ * Two rules follow from that:
+ *
+ *  1. A message written by our own API for a person (`Incorrect email or
+ *     password`) is the best thing to show, so prefer it.
+ *  2. A message produced by the JavaScript runtime is never shown. It names
+ *     an identifier or a property in our source; to a visitor it is noise, and
+ *     it leaks internals. Those become a generic sentence, and the original is
+ *     kept on the result so the caller can log it.
+ */
+/** The error shapes a Stacks API returns. */
+export declare interface ApiErrorBody {
+  message?: string
+  error?: string
+  errors?: Record<string, string[] | string>
+  success?: boolean
+}
+export declare interface UserFacingError {
+  message: string
+  fields?: Record<string, string>
+  unexpected: boolean
+  cause?: unknown
+}

package/dist/composables/request-error.js

@@ -0,0 +1,90 @@
+function isRuntimeDefect(error) {
+  return error instanceof ReferenceError || error instanceof SyntaxError || error instanceof RangeError || error instanceof TypeError && !isNetworkFailure(error);
+}
+function isNetworkFailure(error) {
+  if (!(error instanceof TypeError))
+    return !1;
+  const message = error.message.toLowerCase();
+  return message.includes("fetch") || message.includes("network") || message.includes("load failed") || message.includes("connection");
+}
+function flattenFieldErrors(errors) {
+  if (!errors || typeof errors !== "object")
+    return;
+  const out = {};
+  for (const [field, value] of Object.entries(errors)) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (typeof first === "string" && first.trim())
+      out[field] = first.trim();
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+const UNHELPFUL_LABELS = new Set([
+  "validation failed",
+  "forbidden",
+  "unauthorized",
+  "unauthenticated",
+  "bad request",
+  "not found",
+  "internal server error",
+  "error",
+  "csrf token mismatch",
+  "invalid csrf token",
+  "token mismatch"
+]);
+function usableMessage(body) {
+  for (const candidate of [body?.message, body?.error]) {
+    if (typeof candidate !== "string")
+      continue;
+    const trimmed = candidate.trim();
+    if (trimmed && !UNHELPFUL_LABELS.has(trimmed.toLowerCase()))
+      return trimmed;
+  }
+  return;
+}
+function messageForStatus(status, fields) {
+  if (status === 401)
+    return { message: "Those details did not match an account. Check them and try again.", unexpected: !1 };
+  if (status === 403)
+    return { message: "Your session expired. Refresh the page and try again.", unexpected: !1 };
+  if (status === 404)
+    return { message: "That is not available anymore.", unexpected: !1 };
+  if (status === 409)
+    return { message: "That conflicts with something that already exists.", unexpected: !1 };
+  if (status === 422)
+    return { message: (fields && Object.keys(fields).length === 1 ? Object.values(fields)[0] : void 0) ?? "Some details need fixing before this can be saved.", unexpected: !1 };
+  if (status === 429)
+    return { message: "Too many attempts. Wait a moment, then try again.", unexpected: !1 };
+  if (status >= 500)
+    return { message: "Something went wrong on our end. Try again in a moment.", unexpected: !0 };
+  return { message: "That request could not be completed. Try again.", unexpected: status >= 500 };
+}
+export function describeResponseError(status, body) {
+  const fields = flattenFieldErrors(body?.errors), fromBody = usableMessage(body ?? void 0), fallback = messageForStatus(status, fields);
+  return {
+    message: fromBody ?? fallback.message,
+    ...fields && { fields },
+    unexpected: fallback.unexpected && !fromBody,
+    cause: body ?? void 0
+  };
+}
+export function describeThrownError(error) {
+  if (isNetworkFailure(error))
+    return {
+      message: "Could not reach the server. Check your connection and try again.",
+      unexpected: !1,
+      cause: error
+    };
+  if (isRuntimeDefect(error))
+    return {
+      message: "Something went wrong on our end. Try again in a moment.",
+      unexpected: !0,
+      cause: error
+    };
+  if (error instanceof Error && error.message.trim())
+    return { message: error.message.trim(), unexpected: !1, cause: error };
+  return {
+    message: "Something went wrong. Try again in a moment.",
+    unexpected: !0,
+    cause: error
+  };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/browser",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.189",
+  "version": "0.70.191",
   "description": "Stacks core frontend/browser functionalities.",
   "author": "Chris Breuer",
   "contributors": [
@@ -52,7 +52,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/composables": "0.70.189",
+    "@stacksjs/composables": "0.70.191",
     "@stacksjs/stx": "^0.2.100",
     "bun-query-builder": "^0.1.59",
     "magic-regexp": "^0.11.0"
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "better-dx": "^0.2.17",
-    "@stacksjs/utils": "0.70.189",
+    "@stacksjs/utils": "0.70.191",
     "@stripe/stripe-js": "^9.10.0"
   }
 }