@oatscenter/trellis-svelte 0.100.0-rc.1

package/dist/portal_flow.d.ts

@@ -0,0 +1,24 @@
+import { type BrowserPortalFlowState as PortalFlowState, type PortalBinding } from "@oatscenter/trellis/auth/browser";
+type AuthConfig = {
+    authUrl: string;
+};
+export type CreatePortalFlowConfig = AuthConfig & {
+    getUrl?: () => URL;
+    sessionStorage?: Storage;
+};
+export declare class PortalFlowController {
+    #private;
+    flowId: string | null;
+    state: PortalFlowState | null;
+    loading: boolean;
+    error: string | null;
+    errorCode: string | null;
+    constructor(config: CreatePortalFlowConfig);
+    load(): Promise<PortalFlowState | null>;
+    providerUrl(providerId: string): string;
+    get binding(): PortalBinding;
+    approve(): Promise<PortalFlowState | null>;
+    deny(): Promise<PortalFlowState | null>;
+}
+export declare function createPortalFlow(config: CreatePortalFlowConfig): PortalFlowController;
+export {};

package/dist/portal_flow.js

@@ -0,0 +1,173 @@
+/* portal_flow.js generated by Svelte v5.55.5 */
+import * as $ from 'svelte/internal/client';
+
+import {
+	fetchPortalFlowState,
+	getOrCreatePortalBinding,
+	portalFlowIdFromUrl,
+	portalProviderLoginUrl,
+	submitPortalApproval,
+	TrellisHttpError
+} from "@oatscenter/trellis/auth/browser";
+
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function defaultGetUrl() {
+	return new URL(globalThis.location.href);
+}
+
+export class PortalFlowController {
+	#flowId = $.state(null);
+
+	get flowId() {
+		return $.get(this.#flowId);
+	}
+
+	set flowId(value) {
+		$.set(this.#flowId, value, true);
+	}
+
+	#state = $.state(null);
+
+	get state() {
+		return $.get(this.#state);
+	}
+
+	set state(value) {
+		$.set(this.#state, value, true);
+	}
+
+	#loading = $.state(false);
+
+	get loading() {
+		return $.get(this.#loading);
+	}
+
+	set loading(value) {
+		$.set(this.#loading, value, true);
+	}
+
+	#error = $.state(null);
+
+	get error() {
+		return $.get(this.#error);
+	}
+
+	set error(value) {
+		$.set(this.#error, value, true);
+	}
+
+	#errorCode = $.state(null);
+
+	get errorCode() {
+		return $.get(this.#errorCode);
+	}
+
+	set errorCode(value) {
+		$.set(this.#errorCode, value, true);
+	}
+
+	#config;
+	#getUrl;
+	#sessionStorage;
+	#binding = null;
+
+	constructor(config) {
+		this.#config = { authUrl: config.authUrl };
+		this.#getUrl = config.getUrl ?? defaultGetUrl;
+		this.#sessionStorage = config.sessionStorage ?? globalThis.sessionStorage;
+	}
+
+	async load() {
+		this.loading = true;
+		this.error = null;
+		this.errorCode = null;
+		this.state = null;
+
+		try {
+			const flowId = portalFlowIdFromUrl(this.#getUrl());
+
+			this.flowId = flowId;
+
+			if (!flowId) {
+				this.error = "Missing flow id.";
+				this.errorCode = "missing_flow_id";
+
+				return null;
+			}
+
+			this.#binding = await getOrCreatePortalBinding(flowId, this.#sessionStorage);
+
+			const state = await fetchPortalFlowState(this.#config, flowId, this.#binding);
+
+			this.state = state;
+
+			return state;
+		} catch(error) {
+			this.error = errorMessage(error);
+			this.errorCode = error instanceof TrellisHttpError ? error.code : null;
+			this.state = null;
+
+			return null;
+		} finally {
+			this.loading = false;
+		}
+	}
+
+	providerUrl(providerId) {
+		if (!this.flowId) {
+			throw new Error("Missing flow id.");
+		}
+
+		if (!this.#binding) throw new Error("Portal flow has not loaded.");
+
+		return portalProviderLoginUrl(this.#config, providerId, this.flowId, this.#binding);
+	}
+
+	get binding() {
+		if (!this.#binding) throw new Error("Portal flow has not loaded.");
+
+		return this.#binding;
+	}
+
+	async approve() {
+		return this.#submit("approved");
+	}
+
+	async deny() {
+		return this.#submit("denied");
+	}
+
+	async #submit(decision) {
+		if (!this.flowId) {
+			this.error = "Missing flow id.";
+
+			return null;
+		}
+
+		this.loading = true;
+		this.error = null;
+		this.errorCode = null;
+
+		try {
+			const state = await submitPortalApproval(this.#config, this.flowId, this.binding, decision);
+
+			this.state = state;
+
+			return state;
+		} catch(error) {
+			this.error = errorMessage(error);
+			this.errorCode = error instanceof TrellisHttpError ? error.code : null;
+
+			return null;
+		} finally {
+			this.loading = false;
+		}
+	}
+}
+
+export function createPortalFlow(config) {
+	return new PortalFlowController(config);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@oatscenter/trellis-svelte",
+  "version": "0.100.0-rc.1",
+  "type": "module",
+  "description": "Svelte components and state helpers for Trellis browser applications.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/OATS-Center/trellis#readme",
+  "bugs": {
+    "url": "https://github.com/OATS-Center/trellis/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OATS-Center/trellis.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@nats-io/nats-core": "^3.3.1",
+    "@oatscenter/result": "0.100.0-rc.1",
+    "@oatscenter/trellis": "0.100.0-rc.1",
+    "typebox": "^1.0.15",
+    "ulid": "^3.0.2"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "svelte": "./dist/index.js"
+}

package/src/authorization_context.svelte.ts

@@ -0,0 +1,153 @@
+import {
+  type AuthorizationContextBundle,
+  AuthorizationContextCache,
+  AuthorizationContextRefreshError,
+  type AuthorizationRoutingMaterial,
+  refreshAuthorizationContext,
+  startAuthorizationContextRefresh,
+  type TrellisAuth,
+  type VerifiedAuthorizationContext,
+} from "@oatscenter/trellis/auth";
+
+export type AuthorizationContextStatus =
+  | "empty"
+  | "loading"
+  | "ready"
+  | "refreshing"
+  | "degraded"
+  | "expired"
+  | "authRequired"
+  | "failed";
+
+/** Reactive projection of the shared TypeScript authorization context cache. */
+export class AuthorizationContextController {
+  #cache: AuthorizationContextCache;
+  #context = $state.raw<VerifiedAuthorizationContext>();
+  #status = $state<AuthorizationContextStatus>("empty");
+  #error = $state.raw<unknown>();
+  #stop?: () => void;
+  #epoch = 0;
+
+  constructor(
+    trellisUrl: string,
+    fetch?: typeof globalThis.fetch,
+  ) {
+    this.#cache = new AuthorizationContextCache(trellisUrl, fetch);
+  }
+
+  get context(): VerifiedAuthorizationContext | undefined {
+    return this.#context;
+  }
+
+  get status(): AuthorizationContextStatus {
+    return this.#status;
+  }
+
+  get error(): unknown {
+    return this.#error;
+  }
+
+  get refreshAt(): number | undefined {
+    return this.#context?.refreshAt;
+  }
+
+  get expiresAt(): number | undefined {
+    return this.#context?.context.expiresAt;
+  }
+
+  async install(
+    bundle: AuthorizationContextBundle,
+    routing: AuthorizationRoutingMaterial,
+  ): Promise<void> {
+    this.#status = "loading";
+    this.#error = undefined;
+    try {
+      this.#context = await this.#cache.install(bundle, routing);
+      this.#status = "ready";
+    } catch (error) {
+      this.#status = "failed";
+      this.#error = error;
+      throw error;
+    }
+  }
+
+  async refresh(sessionId: string, auth: TrellisAuth): Promise<void> {
+    const epoch = this.#epoch;
+    const clearGuard = this.#cache.clearGuard();
+    this.#status = "refreshing";
+    try {
+      this.#context = await refreshAuthorizationContext({
+        trellisUrl: this.#cache.trellisUrl,
+        sessionId,
+        auth,
+        cache: this.#cache,
+        shouldInstall: () => epoch === this.#epoch,
+      });
+      this.#status = "ready";
+      this.#error = undefined;
+    } catch (error) {
+      if (epoch !== this.#epoch) return;
+      if (error instanceof AuthorizationContextRefreshError && error.terminal) {
+        if (!(await this.#cache.clearIfCurrent(clearGuard))) {
+          this.#context = this.#cache.current();
+          this.#status = "ready";
+          this.#error = undefined;
+          return;
+        }
+        this.#context = undefined;
+      }
+      this.#status = error instanceof AuthorizationContextRefreshError &&
+          error.terminal
+        ? "authRequired"
+        : this.#context?.context.expiresAt !== undefined &&
+            this.#context.context.expiresAt <= this.#cache.correctedNowSeconds()
+        ? "expired"
+        : "degraded";
+      this.#error = error;
+      throw error;
+    }
+  }
+
+  async refreshNow(sessionId: string, auth: TrellisAuth): Promise<void> {
+    await this.refresh(sessionId, auth);
+  }
+
+  start(sessionId: string, auth: TrellisAuth): void {
+    this.stop();
+    if (!this.#context) this.#status = "refreshing";
+    this.#stop = startAuthorizationContextRefresh({
+      trellisUrl: this.#cache.trellisUrl,
+      sessionId,
+      auth,
+      cache: this.#cache,
+      onRefresh: (context) => {
+        this.#context = context;
+        this.#status = "ready";
+        this.#error = undefined;
+      },
+      onTerminalFailure: (error) => {
+        this.#context = undefined;
+        this.#status = "authRequired";
+        this.#error = error;
+      },
+      onTransientFailure: (error) => {
+        this.#status = "degraded";
+        this.#error = error;
+      },
+    });
+  }
+
+  stop(): void {
+    this.#stop?.();
+    this.#stop = undefined;
+  }
+
+  async clear(): Promise<void> {
+    this.#epoch += 1;
+    this.stop();
+    await this.#cache.clear();
+    this.#context = undefined;
+    this.#status = "empty";
+    this.#error = undefined;
+  }
+}

package/src/components/TrellisContextProvider.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import {
+    provideConnectedTrellisContext,
+    type TrellisAppOwner,
+    type TrellisContextClient,
+  } from "../context.svelte.ts";
+
+  type Props = {
+    trellisApp: TrellisAppOwner;
+    trellis: TrellisContextClient;
+    children: Snippet;
+  };
+
+  const { trellisApp, trellis, children }: Props = $props();
+
+  function installContext(): void {
+    provideConnectedTrellisContext(trellisApp, trellis);
+  }
+
+  installContext();
+</script>
+
+{@render children()}

package/src/components/TrellisProvider.svelte

@@ -0,0 +1,192 @@
+<script lang="ts" generics="TContract extends TrellisParticipantLike">
+  import {
+    classifyBrowserAuthError,
+    ClientAuthHandledError,
+    TrellisClient,
+    type ClientAuthOptions,
+  } from "@oatscenter/trellis";
+  import { onMount } from "svelte";
+  import type {
+    TrellisClientFor,
+    TrellisParticipantLike,
+  } from "../context.svelte.ts";
+  import { resolveTrellisAppUrl } from "../context.svelte.ts";
+  import TrellisContextProvider from "./TrellisContextProvider.svelte";
+  import type { TrellisProviderProps } from "./TrellisProvider.types.ts";
+
+  const {
+    trellisApp,
+    auth,
+    client,
+    children,
+    loading,
+    recoveringAuth,
+    error: errorSnippet,
+    onAuthRequired,
+    onRecoverableAuthError,
+  }: TrellisProviderProps<TContract> = $props();
+
+  type ProviderState = "connecting" | "connected" | "auth_handled" | "failed";
+
+  let trellis = $state<TrellisClientFor<TContract> | null>(null);
+  let connectError = $state<unknown>(null);
+  let providerState = $state<ProviderState>("connecting");
+
+  type SerializableTrellisError = {
+    message?: unknown;
+    code?: unknown;
+    hint?: unknown;
+    context?: unknown;
+  };
+
+  function maybeSerializableError(
+    value: unknown,
+  ): SerializableTrellisError | undefined {
+    if (!value || typeof value !== "object" || !("toSerializable" in value)) {
+      return undefined;
+    }
+    const serialize = value.toSerializable;
+    if (typeof serialize !== "function") return undefined;
+    const serialized = serialize.call(value);
+    return serialized && typeof serialized === "object"
+      ? (serialized as SerializableTrellisError)
+      : undefined;
+  }
+
+  function contextRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
+  }
+
+  function logConnectionError(error: unknown): void {
+    const serialized = maybeSerializableError(error);
+    const context = contextRecord(serialized?.context);
+    const causeMessage =
+      typeof context?.causeMessage === "string"
+        ? context.causeMessage
+        : undefined;
+    const message =
+      typeof serialized?.message === "string"
+        ? serialized.message
+        : error instanceof Error
+          ? error.message
+          : String(error);
+
+    console.error("TrellisProvider failed to connect", {
+      message,
+      code: serialized?.code,
+      hint: serialized?.hint,
+      causeMessage,
+      context: serialized?.context,
+      error,
+    });
+  }
+
+  onMount(() => {
+    let active = true;
+
+    function withBrowserAuthDefaults(
+      authOptions: ClientAuthOptions | undefined,
+    ): ClientAuthOptions {
+      if (authOptions?.mode === "session_key") {
+        return authOptions;
+      }
+
+      return {
+        ...authOptions,
+        currentUrl:
+          authOptions?.currentUrl ?? (() => new URL(window.location.href)),
+      };
+    }
+
+    const connectAuth = withBrowserAuthDefaults(auth);
+    const trellisUrl = resolveTrellisAppUrl(trellisApp.trellisUrl);
+    if (!trellisUrl) {
+      connectError = new TypeError(
+        "Expected trellisApp to resolve a Trellis URL",
+      );
+      providerState = "failed";
+      return;
+    }
+
+    void (async () => {
+      try {
+        const connected = await TrellisClient.connect({
+          ...client,
+          trellisUrl,
+          participant: trellisApp.participant,
+          auth: connectAuth,
+          onAuthRequired: onAuthRequired
+            ? async (ctx) => {
+                await onAuthRequired(ctx.loginUrl, ctx);
+                return { status: "handled" };
+              }
+            : undefined,
+        }).orThrow();
+
+        if (active) {
+          trellis = connected;
+          providerState = "connected";
+        } else {
+          await connected.connection.close();
+        }
+      } catch (error) {
+        if (!active) 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";
+      }
+    })();
+
+    return () => {
+      active = false;
+      const connected = trellis;
+      trellis = null;
+      providerState = "connecting";
+      if (connected) {
+        void connected.connection.close();
+      }
+    };
+  });
+</script>
+
+{#if trellis}
+  <TrellisContextProvider {trellisApp} {trellis} {children} />
+{: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

@@ -0,0 +1,28 @@
+import type {
+  ClientAuthOptions,
+  ClientAuthRequiredContext,
+  ClientOpts,
+} from "@oatscenter/trellis";
+import type { Snippet } from "svelte";
+import type {
+  TrellisAppOwner,
+  TrellisParticipantLike,
+} from "../context.svelte.ts";
+
+/** Props accepted by the Svelte Trellis provider component. */
+export type TrellisProviderProps<
+  TContract extends TrellisParticipantLike = TrellisParticipantLike,
+> = {
+  trellisApp: TrellisAppOwner<TContract>;
+  auth?: ClientAuthOptions;
+  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>;
+};