@qlever-llc/trellis-svelte 0.10.18-rc.1 → 0.10.19

package/dist/components/TrellisProvider.svelte

@@ -1,5 +1,6 @@
 <script lang="ts" generics="TContract extends TrellisContractLike">
   import {
+    classifyBrowserAuthError,
     ClientAuthHandledError,
     TrellisClient,
     type ClientAuthOptions,
@@ -17,12 +18,17 @@
     client,
     children,
     loading,
+    recoveringAuth,
     error: errorSnippet,
     onAuthRequired,
+    onRecoverableAuthError,
   }: TrellisProviderProps<TContract> = $props();
 
+  type ProviderState = "connecting" | "connected" | "auth_handled" | "failed";
+
   let trellis = $state<ConnectedTrellisClient<TContract> | null>(null);
   let connectError = $state<unknown>(null);
+  let providerState = $state<ProviderState>("connecting");
 
   type SerializableTrellisError = {
     message?: unknown;
@@ -98,6 +104,7 @@
       connectError = new TypeError(
         "Expected trellisApp to resolve a Trellis URL",
       );
+      providerState = "failed";
       return;
     }
 
@@ -118,14 +125,43 @@
 
         if (active) {
           trellis = connected;
+          providerState = "connected";
         } else {
           await connected.connection.close();
         }
       } catch (error) {
         if (!active) return;
-        if (error instanceof ClientAuthHandledError) return;
+        if (error instanceof ClientAuthHandledError) {
+          providerState = "auth_handled";
+          return;
+        }
+        const authRecovery = classifyBrowserAuthError(error);
+        if (authRecovery.recoverable) {
+          if (onRecoverableAuthError) {
+            providerState = "auth_handled";
+            try {
+              await onRecoverableAuthError(error);
+              return;
+            } catch (recoveryError) {
+              if (!active) return;
+              console.error("TrellisProvider auth recovery callback failed", {
+                recoveryError,
+                error,
+              });
+              logConnectionError(recoveryError);
+              connectError = recoveryError;
+              providerState = "failed";
+              return;
+            }
+          }
+          if (recoveringAuth) {
+            providerState = "auth_handled";
+            return;
+          }
+        }
         logConnectionError(error);
         connectError = error;
+        providerState = "failed";
       }
     })();
 
@@ -133,6 +169,7 @@
       active = false;
       const connected = trellis;
       trellis = null;
+      providerState = "connecting";
       if (connected) {
         void connected.connection.close();
       }
@@ -142,10 +179,12 @@
 
 {#if trellis}
   <TrellisContextProvider {trellisApp} {trellis} {children} />
-{:else if connectError}
+{:else if providerState === "failed" && connectError}
   {#if errorSnippet}
     {@render errorSnippet(connectError)}
   {/if}
+{:else if providerState === "auth_handled" && recoveringAuth}
+  {@render recoveringAuth()}
 {:else if loading}
   {@render loading()}
 {/if}

package/dist/components/TrellisProvider.types.d.ts

@@ -8,6 +8,8 @@ export type TrellisProviderProps<TContract extends TrellisContractLike = Trellis
     client?: ClientOpts;
     children: Snippet;
     loading?: Snippet;
+    recoveringAuth?: Snippet;
     error?: Snippet<[unknown]>;
     onAuthRequired?: (loginUrl: string, context: ClientAuthRequiredContext) => void | Promise<void>;
+    onRecoverableAuthError?: (error: unknown) => void | Promise<void>;
 };

package/dist/portal_flow.d.ts

@@ -2,12 +2,19 @@ import { type AuthConfig, type BrowserPortalFlowState as PortalFlowState } from
 export type CreatePortalFlowConfig = AuthConfig & {
     getUrl?: () => URL;
 };
+export type PortalFlowErrorClassification = {
+    kind: string;
+    recoverable: boolean;
+    reason?: string;
+    code?: string;
+};
 export declare class PortalFlowController {
     #private;
     flowId: string | null;
     state: PortalFlowState | null;
     loading: boolean;
     error: string | null;
+    errorClassification: PortalFlowErrorClassification | null;
     constructor(config: CreatePortalFlowConfig);
     load(): Promise<PortalFlowState | null>;
     providerUrl(providerId: string): string;

package/dist/portal_flow.js

@@ -8,6 +8,116 @@ import {
 	submitPortalApproval
 } from "@qlever-llc/trellis/auth/browser";
 
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
+
+function normalize(value) {
+	return value.trim().toLowerCase().replaceAll("-", "_").replaceAll(" ", "_");
+}
+
+const EXPIRED_FLOW_VALUES = new Set([
+	"flow_expired",
+	"flow_not_found",
+	"missing_flow",
+	"missing_flow_id",
+	"expired",
+	"trellis.auth.bind_expired",
+	"trellis.auth.flow_expired"
+]);
+
+const AUTH_REQUIRED_VALUES = new Set([
+	"auth_required",
+	"session_not_found",
+	"session_expired",
+	"trellis.bootstrap.auth_required",
+	"trellis.auth.session_not_found",
+	"trellis.auth.session_expired"
+]);
+
+function stringSignal(record, key) {
+	const value = record[key];
+
+	return typeof value === "string" ? value : undefined;
+}
+
+function collectErrorSignals(error) {
+	const values = [error];
+
+	if (isRecord(error) && isRecord(error.context)) values.push(error.context);
+
+	return values.flatMap((value) => {
+		if (typeof value === "string") return [{ message: value }];
+		if (!isRecord(value)) return [];
+
+		const code = stringSignal(value, "code") ?? stringSignal(value, "error");
+		const reason = stringSignal(value, "reason") ?? stringSignal(value, "status");
+
+		const message = value instanceof Error
+			? value.message
+			: stringSignal(value, "causeMessage") ?? stringSignal(value, "message");
+
+		return code || reason || message
+			? [
+				{
+					...code ? { code } : {},
+					...reason ? { reason } : {},
+					...message ? { message } : {}
+				}
+			]
+			: [];
+	});
+}
+
+function matchingSignal(signals, values, messages) {
+	return signals.find((signal) => {
+		const identifiers = [signal.code, signal.reason];
+
+		return identifiers.some((value) => value && values.has(normalize(value))) || messages.some((pattern) => pattern.test(signal.message?.toLowerCase() ?? ""));
+	});
+}
+
+function classification(kind, recoverable, signal) {
+	const reason = signal?.reason ?? signal?.code ?? signal?.message;
+
+	return {
+		kind,
+		recoverable,
+		...reason ? { reason } : {},
+		...signal?.code ? { code: signal.code } : {}
+	};
+}
+
+function classifyPortalFlowError(error) {
+	const signals = collectErrorSignals(error);
+
+	const expiredFlow = matchingSignal(signals, EXPIRED_FLOW_VALUES, [
+		/flow .*expired/,
+		/flow .*not found/,
+		/missing flow/,
+		/sign\-in .*expired/
+	]);
+
+	if (expiredFlow) {
+		return classification("recoverable_expired_flow", true, expiredFlow);
+	}
+
+	const authRequired = matchingSignal(signals, AUTH_REQUIRED_VALUES, [
+		/auth required/,
+		/session .*expired/,
+		/session .*not found/,
+		/requires sign\-in/,
+		/requires signin/,
+		/requires authentication/
+	]);
+
+	if (authRequired) {
+		return classification("recoverable_auth_required", true, authRequired);
+	}
+
+	return classification("unknown", false);
+}
+
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -57,6 +167,16 @@ export class PortalFlowController {
 		$.set(this.#error, value, true);
 	}
 
+	#errorClassification = $.state(null);
+
+	get errorClassification() {
+		return $.get(this.#errorClassification);
+	}
+
+	set errorClassification(value) {
+		$.set(this.#errorClassification, value, true);
+	}
+
 	#config;
 	#getUrl;
 
@@ -68,6 +188,7 @@ export class PortalFlowController {
 	async load() {
 		this.loading = true;
 		this.error = null;
+		this.errorClassification = null;
 		this.state = null;
 
 		try {
@@ -88,6 +209,7 @@ export class PortalFlowController {
 			return state;
 		} catch(error) {
 			this.error = errorMessage(error);
+			this.errorClassification = classifyPortalFlowError(error);
 			this.state = null;
 
 			return null;
@@ -115,12 +237,14 @@ export class PortalFlowController {
 	async #submit(decision) {
 		if (!this.flowId) {
 			this.error = "Missing flow id.";
+			this.errorClassification = null;
 
 			return null;
 		}
 
 		this.loading = true;
 		this.error = null;
+		this.errorClassification = null;
 
 		try {
 			const state = await submitPortalApproval(this.#config, this.flowId, decision);
@@ -130,6 +254,7 @@ export class PortalFlowController {
 			return state;
 		} catch(error) {
 			this.error = errorMessage(error);
+			this.errorClassification = classifyPortalFlowError(error);
 
 			return null;
 		} finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlever-llc/trellis-svelte",
-  "version": "0.10.18-rc.1",
+  "version": "0.10.19",
   "type": "module",
   "description": "Svelte components and state helpers for Trellis browser applications.",
   "license": "Apache-2.0",
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "@nats-io/nats-core": "^3.3.1",
-    "@qlever-llc/result": "0.10.18-rc.1",
-    "@qlever-llc/trellis": "0.10.18-rc.1",
+    "@qlever-llc/result": "^0.10.19",
+    "@qlever-llc/trellis": "^0.10.19",
     "typebox": "^1.0.15",
     "ulid": "^3.0.2"
   },

package/src/components/TrellisProvider.svelte

@@ -1,5 +1,6 @@
 <script lang="ts" generics="TContract extends TrellisContractLike">
   import {
+    classifyBrowserAuthError,
     ClientAuthHandledError,
     TrellisClient,
     type ClientAuthOptions,
@@ -17,12 +18,17 @@
     client,
     children,
     loading,
+    recoveringAuth,
     error: errorSnippet,
     onAuthRequired,
+    onRecoverableAuthError,
   }: TrellisProviderProps<TContract> = $props();
 
+  type ProviderState = "connecting" | "connected" | "auth_handled" | "failed";
+
   let trellis = $state<ConnectedTrellisClient<TContract> | null>(null);
   let connectError = $state<unknown>(null);
+  let providerState = $state<ProviderState>("connecting");
 
   type SerializableTrellisError = {
     message?: unknown;
@@ -98,6 +104,7 @@
       connectError = new TypeError(
         "Expected trellisApp to resolve a Trellis URL",
       );
+      providerState = "failed";
       return;
     }
 
@@ -118,14 +125,43 @@
 
         if (active) {
           trellis = connected;
+          providerState = "connected";
         } else {
           await connected.connection.close();
         }
       } catch (error) {
         if (!active) return;
-        if (error instanceof ClientAuthHandledError) return;
+        if (error instanceof ClientAuthHandledError) {
+          providerState = "auth_handled";
+          return;
+        }
+        const authRecovery = classifyBrowserAuthError(error);
+        if (authRecovery.recoverable) {
+          if (onRecoverableAuthError) {
+            providerState = "auth_handled";
+            try {
+              await onRecoverableAuthError(error);
+              return;
+            } catch (recoveryError) {
+              if (!active) return;
+              console.error("TrellisProvider auth recovery callback failed", {
+                recoveryError,
+                error,
+              });
+              logConnectionError(recoveryError);
+              connectError = recoveryError;
+              providerState = "failed";
+              return;
+            }
+          }
+          if (recoveringAuth) {
+            providerState = "auth_handled";
+            return;
+          }
+        }
         logConnectionError(error);
         connectError = error;
+        providerState = "failed";
       }
     })();
 
@@ -133,6 +169,7 @@
       active = false;
       const connected = trellis;
       trellis = null;
+      providerState = "connecting";
       if (connected) {
         void connected.connection.close();
       }
@@ -142,10 +179,12 @@
 
 {#if trellis}
   <TrellisContextProvider {trellisApp} {trellis} {children} />
-{:else if connectError}
+{:else if providerState === "failed" && connectError}
   {#if errorSnippet}
     {@render errorSnippet(connectError)}
   {/if}
+{:else if providerState === "auth_handled" && recoveringAuth}
+  {@render recoveringAuth()}
 {:else if loading}
   {@render loading()}
 {/if}

package/src/components/TrellisProvider.types.ts

@@ -18,9 +18,11 @@ export type TrellisProviderProps<
   client?: ClientOpts;
   children: Snippet;
   loading?: Snippet;
+  recoveringAuth?: Snippet;
   error?: Snippet<[unknown]>;
   onAuthRequired?: (
     loginUrl: string,
     context: ClientAuthRequiredContext,
   ) => void | Promise<void>;
+  onRecoverableAuthError?: (error: unknown) => void | Promise<void>;
 };

package/src/portal_flow.svelte.ts

@@ -11,6 +11,136 @@ export type CreatePortalFlowConfig = AuthConfig & {
   getUrl?: () => URL;
 };
 
+export type PortalFlowErrorClassification = {
+  kind: string;
+  recoverable: boolean;
+  reason?: string;
+  code?: string;
+};
+
+type ErrorSignal = {
+  code?: string;
+  reason?: string;
+  message?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object";
+}
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase().replaceAll("-", "_").replaceAll(" ", "_");
+}
+
+const EXPIRED_FLOW_VALUES = new Set([
+  "flow_expired",
+  "flow_not_found",
+  "missing_flow",
+  "missing_flow_id",
+  "expired",
+  "trellis.auth.bind_expired",
+  "trellis.auth.flow_expired",
+]);
+
+const AUTH_REQUIRED_VALUES = new Set([
+  "auth_required",
+  "session_not_found",
+  "session_expired",
+  "trellis.bootstrap.auth_required",
+  "trellis.auth.session_not_found",
+  "trellis.auth.session_expired",
+]);
+
+function stringSignal(
+  record: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function collectErrorSignals(error: unknown): ErrorSignal[] {
+  const values: unknown[] = [error];
+  if (isRecord(error) && isRecord(error.context)) values.push(error.context);
+
+  return values.flatMap((value) => {
+    if (typeof value === "string") return [{ message: value }];
+    if (!isRecord(value)) return [];
+
+    const code = stringSignal(value, "code") ?? stringSignal(value, "error");
+    const reason = stringSignal(value, "reason") ??
+      stringSignal(value, "status");
+    const message = value instanceof Error
+      ? value.message
+      : stringSignal(value, "causeMessage") ?? stringSignal(value, "message");
+
+    return code || reason || message
+      ? [{
+        ...(code ? { code } : {}),
+        ...(reason ? { reason } : {}),
+        ...(message ? { message } : {}),
+      }]
+      : [];
+  });
+}
+
+function matchingSignal(
+  signals: ErrorSignal[],
+  values: ReadonlySet<string>,
+  messages: readonly RegExp[],
+): ErrorSignal | undefined {
+  return signals.find((signal) => {
+    const identifiers = [signal.code, signal.reason];
+    return identifiers.some((value) => value && values.has(normalize(value))) ||
+      messages.some((pattern) =>
+        pattern.test(signal.message?.toLowerCase() ?? "")
+      );
+  });
+}
+
+function classification(
+  kind: string,
+  recoverable: boolean,
+  signal?: ErrorSignal,
+): PortalFlowErrorClassification {
+  const reason = signal?.reason ?? signal?.code ?? signal?.message;
+  return {
+    kind,
+    recoverable,
+    ...(reason ? { reason } : {}),
+    ...(signal?.code ? { code: signal.code } : {}),
+  };
+}
+
+function classifyPortalFlowError(
+  error: unknown,
+): PortalFlowErrorClassification {
+  const signals = collectErrorSignals(error);
+  const expiredFlow = matchingSignal(signals, EXPIRED_FLOW_VALUES, [
+    /flow .*expired/,
+    /flow .*not found/,
+    /missing flow/,
+    /sign\-in .*expired/,
+  ]);
+  if (expiredFlow) {
+    return classification("recoverable_expired_flow", true, expiredFlow);
+  }
+
+  const authRequired = matchingSignal(signals, AUTH_REQUIRED_VALUES, [
+    /auth required/,
+    /session .*expired/,
+    /session .*not found/,
+    /requires sign\-in/,
+    /requires signin/,
+    /requires authentication/,
+  ]);
+  if (authRequired) {
+    return classification("recoverable_auth_required", true, authRequired);
+  }
+
+  return classification("unknown", false);
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -24,6 +154,7 @@ export class PortalFlowController {
   state: PortalFlowState | null = $state(null);
   loading = $state(false);
   error: string | null = $state(null);
+  errorClassification: PortalFlowErrorClassification | null = $state(null);
 
   #config: AuthConfig;
   #getUrl: () => URL;
@@ -36,6 +167,7 @@ export class PortalFlowController {
   async load(): Promise<PortalFlowState | null> {
     this.loading = true;
     this.error = null;
+    this.errorClassification = null;
     this.state = null;
 
     try {
@@ -51,6 +183,7 @@ export class PortalFlowController {
       return state;
     } catch (error) {
       this.error = errorMessage(error);
+      this.errorClassification = classifyPortalFlowError(error);
       this.state = null;
       return null;
     } finally {
@@ -79,11 +212,13 @@ export class PortalFlowController {
   ): Promise<PortalFlowState | null> {
     if (!this.flowId) {
       this.error = "Missing flow id.";
+      this.errorClassification = null;
       return null;
     }
 
     this.loading = true;
     this.error = null;
+    this.errorClassification = null;
 
     try {
       const state = await submitPortalApproval(
@@ -95,6 +230,7 @@ export class PortalFlowController {
       return state;
     } catch (error) {
       this.error = errorMessage(error);
+      this.errorClassification = classifyPortalFlowError(error);
       return null;
     } finally {
       this.loading = false;