@qlever-llc/trellis-svelte 0.5.1 → 0.6.0

package/README.md

@@ -4,6 +4,6 @@ Svelte integration for Trellis browser applications.
 
 Provides `TrellisProvider` for app-level wiring, along with reactive helpers for auth state, NATS connection state, and Trellis client state.
 
-Prefer `getTrellisFor(contract)` in app code so the client stays typed from the same contract passed to `TrellisProvider`.
+Prefer `createTrellisApp(...)` for app-scoped auth creation and typed `app.getTrellis()` access without passing the contract around at every call site.
 
-Uses the contract/runtime model from `@qlever-llc/trellis-contracts` and `@qlever-llc/trellis`.
+Uses the contract/runtime model from `@qlever-llc/trellis/contracts` and `@qlever-llc/trellis`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlever-llc/trellis-svelte",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "Svelte components and state helpers for Trellis browser applications.",
   "license": "Apache-2.0",
@@ -28,11 +28,7 @@
   },
   "dependencies": {
     "@nats-io/nats-core": "^3.3.1",
-    "@qlever-llc/trellis-auth": "^0.5.1",
-    "@qlever-llc/trellis-contracts": "^0.5.1",
-    "@qlever-llc/trellis-result": "^0.5.1",
-    "@qlever-llc/trellis-sdk-auth": "^0.5.1",
-    "@qlever-llc/trellis": "^0.5.1",
+    "@qlever-llc/trellis": "^0.6.0",
     "typebox": "^1.0.15"
   },
   "peerDependencies": {

package/src/components/TrellisProvider.svelte

@@ -1,29 +1,27 @@
 <script lang="ts">
   import type { NatsConnection } from "@nats-io/nats-core";
-  import { AsyncResult } from "@qlever-llc/trellis-result";
-  import type { Snippet } from "svelte";
+  import { AsyncResult } from "@qlever-llc/result";
   import { onDestroy } from "svelte";
+  import type { Snippet } from "svelte";
   import {
+    setAppContext,
     setAuthContext,
     setNatsStateContext,
     setTrellisContext,
   } from "../context.svelte.ts";
-  import { type AuthState, type AuthStateConfig, type BindErrorResult, createAuthState } from "../state/auth.svelte.ts";
+  import type { AuthState, BindErrorResult } from "../state/auth.svelte.ts";
   import { createNatsState, type NatsState } from "../state/nats.svelte.ts";
-  import {
-    createTrellisState,
-    type TrellisClientContract,
-    type TrellisState,
-  } from "../state/trellis.svelte.ts";
+  import { createTrellisState, type TrellisState } from "../state/trellis.svelte.ts";
+
+  type TrellisApp = {
+    auth: AuthState;
+  };
 
   type Props = {
     children: Snippet;
     loading?: Snippet;
-    authUrl: string;
-    natsServers: string[];
-    serviceName?: string;
-    contract?: TrellisClientContract;
-    loginPath?: string;
+    bindError?: Snippet<[BindErrorResult]>;
+    app: TrellisApp;
     onAuthExpired?: () => void;
     onAuthFailed?: (error: unknown) => void;
     onAuthRequired?: (redirectTo: string) => void;
@@ -36,14 +34,11 @@
     onNatsError?: (error: Error) => void;
   };
 
-  const {
+  let {
     children,
     loading,
-    authUrl,
-    natsServers,
-    serviceName = "app",
-    contract,
-    loginPath = "/login",
+    bindError,
+    app,
     onAuthExpired,
     onAuthFailed,
     onAuthRequired,
@@ -56,63 +51,59 @@
     onNatsError,
   }: Props = $props();
 
+  let bindErrorResult = $state<BindErrorResult | null>(null);
+
   type InitContext = {
     auth: AuthState;
     nats: NatsState;
     trellis: TrellisState;
   };
+  const isBrowser = typeof window !== "undefined";
 
-  class AuthRequiredError extends Error {
-    constructor() {
-      super("Authentication required");
+  function getRedirectTo(): string {
+    if (typeof window === "undefined") {
+      return "/";
     }
-  }
 
-  class BindFailedError extends Error {
-    constructor() {
-      super("Bind failed");
-    }
+    return window.location.pathname + window.location.search;
   }
 
-  function createProviderAuthState(): AuthState {
-    const config: AuthStateConfig = {
-      authUrl,
-      loginPath,
-      contract,
-    };
+  function redirectToLogin(redirectTo: string): void {
+    if (typeof window === "undefined") return;
 
-    return createAuthState(config);
+    const url = new URL(app.auth.loginPath, window.location.origin);
+    url.searchParams.set("redirectTo", redirectTo);
+    window.location.href = url.toString();
   }
 
-  const authState = createProviderAuthState();
-
-  function getRedirectTo(): string {
-    if (typeof window === "undefined") {
-      return "/";
+  function handleAuthRequired(): void {
+    const redirectTo = getRedirectTo();
+    onAuthRequired?.(redirectTo);
+    if (!onAuthRequired) {
+      redirectToLogin(redirectTo);
     }
-
-    return window.location.pathname + window.location.search;
   }
 
-  async function initialize(): Promise<InitContext> {
+  async function initialize(): Promise<InitContext | null> {
     const result = await AsyncResult.try(async () => {
+      const authState = app.auth;
+
       await authState.init();
       const bindResult = await authState.handleCallback();
       authState.cleanupCallbackUrl();
 
       if (bindResult !== null && bindResult.status !== "bound") {
+        bindErrorResult = bindResult;
         onBindError?.(bindResult);
-        throw new BindFailedError();
+        return null;
       }
 
       if (!authState.isAuthenticated) {
-        onAuthRequired?.(getRedirectTo());
-        throw new AuthRequiredError();
+        handleAuthRequired();
+        return null;
       }
 
-      const effectiveNatsServers = authState.natsServers ?? natsServers;
       const natsState = await createNatsState(authState, {
-        servers: effectiveNatsServers,
         onConnecting: onNatsConnecting,
         onConnected: onNatsConnected,
         onDisconnect: onNatsDisconnect,
@@ -120,13 +111,13 @@
         onReconnect: onNatsReconnect,
         onError: onNatsError,
         onAuthRequired: () => {
-          onAuthRequired?.(getRedirectTo());
+          onAuthExpired?.();
+          handleAuthRequired();
         },
       });
 
       const trellisState = await createTrellisState(authState, natsState, {
-        serviceName,
-        contract,
+        contract: authState.contract,
       });
 
       return {
@@ -138,10 +129,7 @@
 
     if (result.isErr()) {
       const error = result.error;
-      if (error instanceof AuthRequiredError || error instanceof BindFailedError) {
-        throw error;
-      }
-      authState.clearAuth();
+      app.auth.clearAuth();
       onAuthFailed?.(error);
       throw error;
     }
@@ -154,30 +142,54 @@
     });
   }
 
-  const initPromise = initialize();
-  const natsStatePromise = initPromise.then((ctx) => ctx.nats) as Promise<NatsState>;
-  const trellisPromise = initPromise.then((ctx) => ctx.trellis.trellis) as Promise<unknown>;
-  const natsPromise = initPromise.then((ctx) => ctx.nats.nc) as Promise<NatsConnection>;
-
-  setAuthContext(authState);
-  setNatsStateContext(natsStatePromise);
-  setTrellisContext({
-    trellis: trellisPromise as never,
-    nats: natsPromise,
-  });
+  const initPromise = isBrowser ? initialize() : null;
+  const readyPromise: Promise<InitContext> | null = initPromise?.then((ctx) => {
+    if (!ctx) {
+      throw new Error("Trellis context is not available");
+    }
+    return ctx;
+  }) ?? null;
+  const natsStatePromise: Promise<NatsState> | null = readyPromise?.then((ctx) => ctx.nats) ?? null;
+  const trellisPromise: Promise<TrellisState["trellis"]> | null = readyPromise?.then((ctx) => ctx.trellis.trellis) ?? null;
+  const natsPromise: Promise<NatsConnection> | null = readyPromise?.then((ctx) => ctx.nats.nc) ?? null;
+
+  if (readyPromise && natsStatePromise && trellisPromise && natsPromise) {
+    void readyPromise.catch(() => {});
+    setAppContext(() => app);
+    setAuthContext(() => app.auth);
+    setNatsStateContext(natsStatePromise);
+    setTrellisContext({
+      trellis: trellisPromise,
+      nats: natsPromise,
+    });
+  }
 
   onDestroy(() => {
-    void initPromise.then((ctx) => {
+    if (!readyPromise) return;
+
+    void readyPromise.then((ctx) => {
       ctx.trellis.stop();
       void ctx.nats.disconnect();
     });
   });
 </script>
 
-{#await initPromise}
+{#if !isBrowser}
   {#if loading}
     {@render loading()}
   {/if}
-{:then}
-  {@render children()}
-{/await}
+{:else}
+  {#await initPromise}
+    {#if loading}
+      {@render loading()}
+    {/if}
+  {:then ctx}
+    {#if bindErrorResult}
+      {#if bindError}
+        {@render bindError(bindErrorResult)}
+      {/if}
+    {:else if ctx}
+      {@render children()}
+    {/if}
+  {/await}
+{/if}

package/src/context.svelte.ts

@@ -1,17 +1,12 @@
+import type { BaseError, Result } from "@qlever-llc/result";
 import type { NatsConnection } from "@nats-io/nats-core";
-import type { Trellis } from "@qlever-llc/trellis";
-import type { InferSchemaType, TrellisAPI } from "@qlever-llc/trellis-contracts";
-import { getContext, setContext } from "svelte";
-import type { AuthState } from "./state/auth.svelte.ts";
+import type { InferSchemaType, Trellis, TrellisAPI } from "@qlever-llc/trellis";
+import { createContext } from "svelte";
+import { createAuthState, type AuthState, type AuthStateConfig, type SignInOptions } from "./state/auth.svelte.ts";
 import type { NatsState } from "./state/nats.svelte.ts";
 
-const TRELLIS_KEY = Symbol("trellis");
-const NATS_KEY = Symbol("nats");
-const NATS_STATE_KEY = Symbol("nats-state");
-const AUTH_KEY = Symbol("auth");
-
 type TrellisContext = {
-  trellis: Promise<unknown>;
+  trellis: Promise<Trellis<TrellisAPI>>;
   nats: Promise<NatsConnection>;
 };
 
@@ -25,60 +20,83 @@ type RequestOpts = {
   timeout?: number;
 };
 
-type RpcMapFor<TA extends TrellisAPI> = {
-  [M in keyof TA["rpc"] & string]: {
-    input: InferSchemaType<TA["rpc"][M]["input"]>;
-    output: InferSchemaType<TA["rpc"][M]["output"]>;
-  };
-};
-
-type TypedRequestSurface<TA extends TrellisAPI> = {
-  requestOrThrow<M extends keyof RpcMapFor<TA> & string>(
+type TypedTrellis<TA extends TrellisAPI> = Omit<Trellis<TrellisAPI>, "request" | "requestOrThrow"> & {
+  request<M extends keyof TA["rpc"] & string>(
     method: M,
-    input: RpcMapFor<TA>[M]["input"],
+    input: InferSchemaType<TA["rpc"][M]["input"]>,
     opts?: RequestOpts,
-  ): Promise<RpcMapFor<TA>[M]["output"]>;
+  ): Promise<Result<InferSchemaType<TA["rpc"][M]["output"]>, BaseError>>;
+  requestOrThrow<M extends keyof TA["rpc"] & string>(
+    method: M,
+    input: InferSchemaType<TA["rpc"][M]["input"]>,
+    opts?: RequestOpts,
+  ): Promise<InferSchemaType<TA["rpc"][M]["output"]>>;
+};
+
+function createTypedTrellis<TA extends TrellisAPI>(trellis: Trellis<TrellisAPI>): TypedTrellis<TA> {
+  return trellis as TypedTrellis<TA>;
+}
+
+export type BoundTrellisApp<TContract extends TrellisContractLike> = {
+  auth: AuthState;
+  signIn: (options?: SignInOptions) => Promise<never>;
+  getTrellis: () => Promise<TypedTrellis<TContract["API"]["trellis"]>>;
 };
 
-type TypedTrellis<TA extends TrellisAPI> =
-  & Omit<Trellis<TA>, "requestOrThrow">
-  & TypedRequestSurface<TA>;
+const [getTrellisContext, setTrellisContextValue] = createContext<TrellisContext>();
+const [getNatsStateContext, setNatsStateContextValue] = createContext<Promise<NatsState>>();
+const [getAuthContext, setAuthContextValue] = createContext<() => AuthState>();
+const [getAppContext, setAppContextValue] = createContext<() => unknown>();
 
-export function setTrellisContext<TA extends TrellisAPI>(
-  ctx: { trellis: Promise<Trellis<TA>>; nats: Promise<NatsConnection> },
+export function setTrellisContext(
+  ctx: TrellisContext,
 ): void {
-  setContext(TRELLIS_KEY, ctx.trellis as unknown as Promise<unknown>);
-  setContext(NATS_KEY, ctx.nats);
+  setTrellisContextValue(ctx);
 }
 
 export function setNatsStateContext(natsState: Promise<NatsState>): void {
-  setContext(NATS_STATE_KEY, natsState);
+  setNatsStateContextValue(natsState);
 }
 
-export function setAuthContext(auth: AuthState): void {
-  setContext(AUTH_KEY, auth);
+export function setAuthContext(getAuth: () => AuthState): void {
+  setAuthContextValue(getAuth);
 }
 
-export function getTrellis<TA extends TrellisAPI = TrellisAPI>(): Promise<Trellis<TA>> {
-  return getContext<Promise<unknown>>(TRELLIS_KEY) as Promise<Trellis<TA>>;
+export function setAppContext(getApp: () => unknown): void {
+  setAppContextValue(getApp);
 }
 
-export function getTrellisFor<TContract extends TrellisContractLike>(
-  _contract: TContract,
-): Promise<TypedTrellis<TContract["API"]["trellis"]>> {
-  return getTrellis<TContract["API"]["trellis"]>() as unknown as Promise<
-    TypedTrellis<TContract["API"]["trellis"]>
-  >;
+export function createTrellisApp<TContract extends TrellisContractLike>(
+  config: AuthStateConfig & { contract: TContract },
+): BoundTrellisApp<TContract> {
+  const auth = createAuthState(config);
+
+  let app!: BoundTrellisApp<TContract>;
+  app = {
+    auth,
+    signIn: (options) => auth.signIn(options),
+    getTrellis: () => {
+      if (getAppContext()() !== app) {
+        throw new Error("getTrellis() was called outside the matching TrellisProvider");
+      }
+
+      return getTrellisContext().trellis.then((trellis) =>
+        createTypedTrellis<TContract["API"]["trellis"]>(trellis)
+      );
+    },
+  };
+
+  return app;
 }
 
 export function getNats(): Promise<NatsConnection> {
-  return getContext<Promise<NatsConnection>>(NATS_KEY);
+  return getTrellisContext().nats;
 }
 
 export function getNatsState(): Promise<NatsState> {
-  return getContext<Promise<NatsState>>(NATS_STATE_KEY);
+  return getNatsStateContext();
 }
 
 export function getAuth(): AuthState {
-  return getContext<AuthState>(AUTH_KEY);
+  return getAuthContext()();
 }

package/src/index.ts

@@ -1,6 +1,9 @@
 export { default as TrellisProvider } from "./components/TrellisProvider.svelte";
-export { getAuth, getNats, getNatsState, getTrellis, getTrellisFor, setTrellisContext } from "./context.svelte.ts";
-export { AuthState, type BindErrorResult, type BindResult, createAuthState } from "./state/auth.svelte.ts";
+export { createTrellisApp, getAuth, getNats, getNatsState, setTrellisContext } from "./context.svelte.ts";
+export type { BoundTrellisApp } from "./context.svelte.ts";
+export { createPortalFlow, PortalFlowController, type CreatePortalFlowConfig } from "./portal_flow.svelte.ts";
+export { AuthState, type BindErrorResult, type BindResult, createAuthState, type SignInOptions } from "./state/auth.svelte.ts";
 export type { NatsStateConfig, Status as NatsStatus } from "./state/nats.svelte.ts";
 export { createNatsState, NatsState } from "./state/nats.svelte.ts";
+export type { TrellisClientContract, TrellisStateConfig } from "./state/trellis.svelte.ts";
 export { createTrellisState, TrellisState } from "./state/trellis.svelte.ts";

package/src/portal_flow.svelte.ts

@@ -0,0 +1,101 @@
+import {
+  fetchPortalFlowState,
+  portalFlowIdFromUrl,
+  portalProviderLoginUrl,
+  type PortalFlowState,
+  submitPortalApproval,
+  type AuthConfig,
+} from "@qlever-llc/trellis/auth";
+
+export type CreatePortalFlowConfig = AuthConfig & {
+  getUrl?: () => URL;
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function defaultGetUrl(): URL {
+  return new URL(globalThis.location.href);
+}
+
+export class PortalFlowController {
+  flowId: string | null = $state(null);
+  state: PortalFlowState | null = $state(null);
+  loading = $state(false);
+  error: string | null = $state(null);
+
+  #config: AuthConfig;
+  #getUrl: () => URL;
+
+  constructor(config: CreatePortalFlowConfig) {
+    this.#config = { authUrl: config.authUrl };
+    this.#getUrl = config.getUrl ?? defaultGetUrl;
+  }
+
+  async load(): Promise<PortalFlowState | null> {
+    this.loading = true;
+    this.error = null;
+    this.state = null;
+
+    try {
+      const flowId = portalFlowIdFromUrl(this.#getUrl());
+      this.flowId = flowId;
+      if (!flowId) {
+        this.error = "Missing flow id.";
+        return null;
+      }
+
+      const state = await fetchPortalFlowState(this.#config, flowId);
+      this.state = state;
+      return state;
+    } catch (error) {
+      this.error = errorMessage(error);
+      this.state = null;
+      return null;
+    } finally {
+      this.loading = false;
+    }
+  }
+
+  providerUrl(providerId: string): string {
+    if (!this.flowId) {
+      throw new Error("Missing flow id.");
+    }
+
+    return portalProviderLoginUrl(this.#config, providerId, this.flowId);
+  }
+
+  async approve(): Promise<PortalFlowState | null> {
+    return this.#submit("approved");
+  }
+
+  async deny(): Promise<PortalFlowState | null> {
+    return this.#submit("denied");
+  }
+
+  async #submit(decision: "approved" | "denied"): Promise<PortalFlowState | null> {
+    if (!this.flowId) {
+      this.error = "Missing flow id.";
+      return null;
+    }
+
+    this.loading = true;
+    this.error = null;
+
+    try {
+      const state = await submitPortalApproval(this.#config, this.flowId, decision);
+      this.state = state;
+      return state;
+    } catch (error) {
+      this.error = errorMessage(error);
+      return null;
+    } finally {
+      this.loading = false;
+    }
+  }
+}
+
+export function createPortalFlow(config: CreatePortalFlowConfig): PortalFlowController {
+  return new PortalFlowController(config);
+}

package/src/state/auth.svelte.ts

@@ -1,20 +1,22 @@
 import {
   type BindResponse,
   type BindSuccessResponse,
+  bindFlow,
   bindSession,
-  buildLoginUrl,
   clearSessionKey,
-  extractAuthErrorFromFragment,
-  extractAuthTokenFromFragment,
   getOrCreateSessionKey,
   getPublicSessionKey,
   type SentinelCreds,
   type SessionKeyHandle,
-} from "@qlever-llc/trellis-auth";
-import { Result } from "@qlever-llc/trellis-result";
+} from "@qlever-llc/trellis/auth";
+import { canonicalizeJsonValue } from "../../../auth/utils.ts";
+import { oauthInitSig } from "../../../auth/browser/session.ts";
+import { Result } from "@qlever-llc/result";
 import { SvelteDate } from "svelte/reactivity";
+import type { TrellisContractV1 } from "@qlever-llc/trellis";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
+import type { TrellisClientContract } from "./trellis.svelte.ts";
 
 export type BindErrorResult =
   | { status: "insufficient_capabilities"; missingCapabilities: string[] }
@@ -24,15 +26,8 @@ export type BindErrorResult =
 
 export type BindResult = { status: "bound" } | BindErrorResult;
 
-const buildLoginHref = buildLoginUrl as unknown as (
-  config: { authUrl: string },
-  provider: string | undefined,
-  redirectTo: string,
-  handle: SessionKeyHandle,
-  contract: Record<string, unknown>,
-) => Promise<string>;
-
 const STORAGE_KEY = "trellis_auth";
+const AUTH_URL_STORAGE_KEY = "trellis_auth_url";
 
 type AuthStateData = {
   handle: SessionKeyHandle | null;
@@ -104,11 +99,88 @@ function clearPersistedAuth(): void {
 }
 
 export type AuthStateConfig = {
-  authUrl: string; // https://auth.example.com
+  authUrl?: string; // https://auth.example.com
   loginPath?: string;
-  contract?: { CONTRACT: Record<string, unknown> };
+  contract?: TrellisClientContract;
+};
+
+export type SignInOptions = {
+  authUrl?: string;
+  redirectTo?: string;
+  landingPath?: string;
+  context?: unknown;
 };
 
+function normalizeAuthUrl(authUrl: string): string {
+  return new URL(authUrl).toString().replace(/\/$/, "");
+}
+
+function encodeJsonForQuery(value: unknown): string {
+  const json = canonicalizeJsonValue(value);
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+async function buildLoginUrl(options: {
+  authUrl: string;
+  redirectTo: string;
+  handle: SessionKeyHandle;
+  contract: Record<string, unknown>;
+  context?: unknown;
+}): Promise<string> {
+  const sessionKey = getPublicSessionKey(options.handle);
+  const sig = await oauthInitSig(options.handle, options.redirectTo, options.context);
+  const url = new URL(`${options.authUrl}/auth/login`);
+
+  url.searchParams.set("redirectTo", options.redirectTo);
+  url.searchParams.set("sessionKey", sessionKey);
+  url.searchParams.set("sig", sig);
+  url.searchParams.set("contract", encodeJsonForQuery(options.contract));
+  if (options.context !== undefined) {
+    url.searchParams.set("context", encodeJsonForQuery(options.context));
+  }
+
+  return url.href;
+}
+
+function loadPersistedAuthUrl(): string | null {
+  if (typeof localStorage === "undefined") return null;
+  const stored = localStorage.getItem(AUTH_URL_STORAGE_KEY);
+  if (!stored) return null;
+
+  return Result.try(() => normalizeAuthUrl(stored)).unwrapOr(null);
+}
+
+function persistAuthUrl(authUrl: string): string {
+  const normalized = normalizeAuthUrl(authUrl);
+  if (typeof localStorage !== "undefined") {
+    localStorage.setItem(AUTH_URL_STORAGE_KEY, normalized);
+  }
+  return normalized;
+}
+
+function resolveRedirectTo(
+  options: SignInOptions,
+  currentUrl: URL,
+): string {
+  if (options.redirectTo) {
+    return new URL(options.redirectTo, currentUrl.origin).toString();
+  }
+
+  const queryRedirect = currentUrl.searchParams.get("redirectTo");
+  if (queryRedirect) {
+    return new URL(queryRedirect, currentUrl.origin).toString();
+  }
+
+  if (options.landingPath) {
+    return new URL(options.landingPath, currentUrl.origin).toString();
+  }
+
+  return currentUrl.toString();
+}
+
 /**
  * Svelte 5 runes-based reactive authentication state.
  *
@@ -132,12 +204,48 @@ export class AuthState {
   #bindingInProgress: Promise<BindResult> | null = null;
 
   constructor(config: AuthStateConfig) {
-    this.#config = config;
+    this.#config = {
+      ...config,
+      authUrl: config.authUrl ? normalizeAuthUrl(config.authUrl) : undefined,
+    };
+  }
+
+  #getConfiguredAuthUrl(): string | null {
+    if (this.#config.authUrl) return this.#config.authUrl;
+
+    const persisted = loadPersistedAuthUrl();
+    if (!persisted) return null;
+
+    this.#config.authUrl = persisted;
+    return persisted;
+  }
+
+  #requireAuthUrl(): string {
+    const authUrl = this.#getConfiguredAuthUrl();
+    if (!authUrl) {
+      throw new Error("Auth URL is not configured");
+    }
+    return authUrl;
+  }
+
+  setAuthUrl(authUrl: string): string {
+    const normalized = persistAuthUrl(authUrl);
+    this.#config.authUrl = normalized;
+    return normalized;
   }
 
   get handle(): SessionKeyHandle | null {
     return this.#state.handle;
   }
+  get authUrl(): string | null {
+    return this.#getConfiguredAuthUrl();
+  }
+  get loginPath(): string {
+    return this.#config.loginPath ?? "/login";
+  }
+  get contract(): TrellisClientContract | undefined {
+    return this.#config.contract;
+  }
   get sessionKey(): string | null {
     return this.#state.handle ? getPublicSessionKey(this.#state.handle) : null;
   }
@@ -169,6 +277,8 @@ export class AuthState {
   async init(): Promise<SessionKeyHandle> {
     if (this.#state.handle) return this.#state.handle;
 
+    this.#getConfiguredAuthUrl();
+
     const handle = await getOrCreateSessionKey();
     this.#state.handle = handle;
 
@@ -188,30 +298,28 @@ export class AuthState {
    * Initiate OAuth sign-in flow by redirecting to the auth provider.
    * This method does not return - it redirects the browser.
    */
-  async signIn(provider: string | undefined, redirectTo: string): Promise<never> {
+  async signIn(options: SignInOptions = {}): Promise<never> {
+    const authUrl = options.authUrl ? this.setAuthUrl(options.authUrl) : this.#requireAuthUrl();
     const handle = await this.init();
-    const url = await buildLoginHref(
-      { authUrl: this.#config.authUrl },
-      provider,
-      redirectTo,
+    const currentUrl = new URL(window.location.href);
+    const url = await buildLoginUrl({
+      authUrl,
+      redirectTo: resolveRedirectTo(options, currentUrl),
       handle,
-      this.#config.contract?.CONTRACT ?? {},
-    );
+      contract: this.#config.contract?.CONTRACT ?? {},
+      context: options.context,
+    });
     window.location.href = url;
-    throw new Error(provider ? `Redirecting to ${provider} for authentication` : "Redirecting to auth for provider selection");
+    throw new Error("Redirecting to auth for provider selection");
   }
 
   async handleCallback(url: string = window.location.href): Promise<BindResult | null> {
     if (this.#bindingInProgress) return this.#bindingInProgress;
 
-    const authError = extractAuthErrorFromFragment(url);
-    if (authError === "approval_denied") return { status: "approval_denied" };
-    if (authError) return { status: "error", message: authError };
-
-    const authToken = extractAuthTokenFromFragment(url);
-    if (!authToken) return null;
+    const flowId = new URL(url).searchParams.get("flowId");
+    if (!flowId) return null;
 
-    this.#bindingInProgress = this.#resolveCallback(authToken);
+    this.#bindingInProgress = this.#resolveCallback(flowId);
     try {
       return await this.#bindingInProgress;
     } finally {
@@ -219,9 +327,9 @@ export class AuthState {
     }
   }
 
-  async #resolveCallback(authToken: string): Promise<BindResult> {
+  async #resolveCallback(flowId: string): Promise<BindResult> {
     try {
-      const response = await this.bind(authToken);
+      const response = await this.bindFlow(flowId);
       return response.status === "bound"
         ? { status: "bound" }
         : { status: "insufficient_capabilities", missingCapabilities: response.missingCapabilities };
@@ -234,12 +342,13 @@ export class AuthState {
   }
 
   /**
-   * Clean up the callback URL by removing the authToken fragment.
+   * Clean up the callback URL by removing the auth flow query params.
    */
   cleanupCallbackUrl(url: string = window.location.href): void {
     const parsed = new URL(url);
-    if (parsed.hash) {
-      parsed.hash = "";
+    if (parsed.searchParams.has("flowId") || parsed.searchParams.has("authError")) {
+      parsed.searchParams.delete("flowId");
+      parsed.searchParams.delete("authError");
       window.history.replaceState({}, "", parsed.pathname + parsed.search);
     }
   }
@@ -255,7 +364,7 @@ export class AuthState {
   async #bind(authToken: string): Promise<BindResponse> {
     const handle = await this.init();
     const response = await bindSession(
-      { authUrl: this.#config.authUrl },
+      { authUrl: this.#requireAuthUrl() },
       handle,
       authToken,
     );
@@ -267,6 +376,21 @@ export class AuthState {
     return response;
   }
 
+  async bindFlow(flowId: string): Promise<BindResponse> {
+    const handle = await this.init();
+    const response = await bindFlow(
+      { authUrl: this.#requireAuthUrl() },
+      handle,
+      flowId,
+    );
+
+    if (response.status === "bound") {
+      this.setBindingToken(response);
+    }
+
+    return response;
+  }
+
   setBindingToken(
     response: Pick<BindSuccessResponse, "bindingToken" | "inboxPrefix" | "expires"> & {
       sentinel?: SentinelCreds;
@@ -326,8 +450,7 @@ export class AuthState {
     this.clearAuth();
     this.#state.handle = null;
 
-    const loginPath = this.#config.loginPath ?? "/login";
-    window.location.href = loginPath;
+    window.location.href = this.loginPath;
     throw new Error("Signed out, redirecting to login");
   }
 }

package/src/state/nats.svelte.ts

@@ -3,20 +3,20 @@ import {
   type NatsConnection,
   wsconnect,
 } from "@nats-io/nats-core";
-import { createClient } from "@qlever-llc/trellis";
+import { createClient, type Trellis } from "@qlever-llc/trellis";
 import {
   getPublicSessionKey,
   natsConnectSigForBindingToken,
   type SentinelCreds,
   type SessionKeyHandle,
   signBytes,
-} from "@qlever-llc/trellis-auth";
-import { AsyncResult, isErr, UnexpectedError } from "@qlever-llc/trellis-result";
+} from "@qlever-llc/trellis/auth";
+import { AsyncResult, UnexpectedError } from "@qlever-llc/result";
 import {
   API as AUTH_API,
   type AuthRenewBindingTokenInput,
   type AuthRenewBindingTokenOutput,
-} from "@qlever-llc/trellis-sdk-auth";
+} from "@qlever-llc/trellis/sdk/auth";
 import type { AuthState } from "./auth.svelte.ts";
 
 const AUTH_RENEW_API = {
@@ -25,19 +25,34 @@ const AUTH_RENEW_API = {
   },
   events: {},
   subjects: {},
+  operations: {},
 } as const;
 
-type AuthRenewClient = {
-  request(
-    method: "Auth.RenewBindingToken",
-    input: AuthRenewBindingTokenInput,
-  ): Promise<{ take(): AuthRenewBindingTokenOutput | unknown }>;
+const AUTH_RENEW_CONTRACT = {
+  API: {
+    trellis: AUTH_RENEW_API,
+  },
+} as const;
+
+function createAuthRenewClient(
+  nc: NatsConnection,
+  handle: SessionKeyHandle,
+): Trellis<typeof AUTH_RENEW_API> {
+  return createClient<typeof AUTH_RENEW_API>(
+    AUTH_RENEW_CONTRACT,
+    nc,
+    {
+      sessionKey: getPublicSessionKey(handle),
+      sign: (data: Uint8Array) => signBytes(handle, data),
+    },
+    { name: "auth-renew" },
+  );
 };
 
 export type Status = "disconnected" | "connecting" | "connected" | "error";
 
 export type NatsStateConfig = {
-  servers: string[];
+  servers?: string[];
   onConnecting?: () => void;
   onConnected?: () => void;
   onDisconnect?: () => void;
@@ -63,19 +78,15 @@ function requireBrowserAuth(authState: AuthState): {
   return { handle, bindingToken, sentinel };
 }
 
-function createAuthRenewClient(
-  nc: NatsConnection,
-  handle: SessionKeyHandle,
-) : AuthRenewClient {
-  return createClient(
-    { API: { trellis: AUTH_RENEW_API } },
-    nc,
-    {
-      sessionKey: getPublicSessionKey(handle),
-      sign: (data: Uint8Array) => signBytes(handle, data),
-    },
-    { name: "auth-renew" },
-  ) as unknown as AuthRenewClient;
+function resolveServers(
+  authState: AuthState,
+  config: NatsStateConfig,
+): string[] {
+  const servers = config.servers ?? authState.natsServers;
+  if (!servers || servers.length === 0) {
+    throw new Error("Not authenticated: missing natsServers from auth state");
+  }
+  return servers;
 }
 
 async function buildNatsAuthToken(
@@ -105,7 +116,7 @@ export class NatsState {
   #handle: SessionKeyHandle;
   #tokenRef: { value: string };
   #sentinel: SentinelCreds;
-  #trellis: AuthRenewClient;
+  #trellis: ReturnType<typeof createAuthRenewClient>;
   #renewTimer: ReturnType<typeof setTimeout> | undefined;
 
   private constructor(
@@ -151,6 +162,7 @@ export class NatsState {
     }
 
     const { handle, bindingToken, sentinel } = requireBrowserAuth(authState);
+    const servers = resolveServers(authState, config);
     const inboxPrefix = authState.inboxPrefix ?? undefined;
     const tokenRef = { value: await buildNatsAuthToken(handle, bindingToken) };
 
@@ -161,7 +173,7 @@ export class NatsState {
     );
 
     const nc = await wsconnect({
-      servers: config.servers,
+      servers,
       authenticator,
       token: tokenRef.value, // auth_token for auth callout
       reconnect: true,
@@ -175,7 +187,7 @@ export class NatsState {
     const state = new NatsState(
       nc,
       "connected",
-      config.servers,
+      servers,
       authState,
       config,
       handle,
@@ -258,13 +270,14 @@ export class NatsState {
   async #renewBindingToken(): Promise<void> {
     const renew = async () => {
       if (this.status !== "connected") return;
-      const res = await this.#trellis.request(
+      const requestOrThrow = this.#trellis.requestOrThrow.bind(this.#trellis) as (
+        method: string,
+        input: unknown,
+      ) => Promise<unknown>;
+      const binding = await requestOrThrow(
         "Auth.RenewBindingToken",
         {} satisfies AuthRenewBindingTokenInput,
-      );
-      const v = res.take();
-      if (isErr(v)) return;
-      const binding = v as AuthRenewBindingTokenOutput;
+      ) as AuthRenewBindingTokenOutput;
       this.#authState.setBindingToken(binding);
       this.#tokenRef.value = await buildNatsAuthToken(
         this.#handle,

package/src/state/trellis.svelte.ts

@@ -1,12 +1,16 @@
-import type { NatsConnection } from "@nats-io/nats-core";
-import { type ClientOpts, createClient, type Trellis, type TrellisAuth } from "@qlever-llc/trellis";
-import { getPublicSessionKey, signBytes } from "@qlever-llc/trellis-auth";
-import { defineContract, type TrellisAPI } from "@qlever-llc/trellis-contracts";
+import {
+  createClient,
+  defineContract,
+  type Trellis,
+  type TrellisAPI,
+  type TrellisContractV1,
+} from "@qlever-llc/trellis";
+import { getPublicSessionKey, signBytes } from "@qlever-llc/trellis/auth";
 import type { AuthState } from "./auth.svelte.ts";
 import type { NatsState } from "./nats.svelte.ts";
 
 export type TrellisClientContract<TApi extends TrellisAPI = TrellisAPI> = {
-  CONTRACT: Record<string, unknown>;
+  CONTRACT: TrellisContractV1;
   CONTRACT_DIGEST: string;
   API: {
     trellis: TApi;
@@ -14,7 +18,6 @@ export type TrellisClientContract<TApi extends TrellisAPI = TrellisAPI> = {
 };
 
 export type TrellisStateConfig<TApi extends TrellisAPI = TrellisAPI> = {
-  serviceName: string;
   contract?: TrellisClientContract<TApi>;
 };
 
@@ -23,7 +26,7 @@ const DEFAULT_TRELLIS_CONTRACT = defineContract({
   displayName: "Trellis Svelte Browser Client",
   description: "Represent a browser client that only uses its locally declared Trellis APIs.",
   kind: "browser",
-});
+}) satisfies TrellisClientContract<TrellisAPI>;
 
 /**
  * Svelte 5 wrapper for Trellis client.
@@ -32,33 +35,36 @@ const DEFAULT_TRELLIS_CONTRACT = defineContract({
  * - Trellis client instance
  * - Session-key based request signing
  */
-export class TrellisState {
-  readonly trellis: Trellis<TrellisAPI>;
+export class TrellisState<TApi extends TrellisAPI = TrellisAPI> {
+  readonly trellis: Trellis<TApi>;
 
-  private constructor(trellis: Trellis<TrellisAPI>) {
+  private constructor(trellis: Trellis<TApi>) {
     this.trellis = trellis;
   }
 
   /**
    * Create a TrellisState instance with proper authentication.
    */
-  static async create<TApi extends TrellisAPI = TrellisAPI>(
+  static async create<TApi extends TrellisAPI>(
     authState: AuthState,
     natsState: NatsState,
     config: TrellisStateConfig<TApi>,
-  ): Promise<TrellisState> {
+  ): Promise<TrellisState<TApi>> {
     const handle = await authState.init();
     const contract = (config.contract ?? DEFAULT_TRELLIS_CONTRACT) as TrellisClientContract<TApi>;
-    const trellis = createClient(
+    const clientName = typeof contract.CONTRACT.id === "string" && contract.CONTRACT.id.length > 0
+      ? contract.CONTRACT.id
+      : "client";
+    const trellis = createClient<TApi>(
       contract,
       natsState.nc,
       {
         sessionKey: getPublicSessionKey(handle),
         sign: (data: Uint8Array) => signBytes(handle, data),
       },
-      { name: config.serviceName },
-    ) as unknown as Trellis<TrellisAPI>;
-    return new TrellisState(trellis);
+      { name: clientName },
+    );
+    return new TrellisState<TApi>(trellis);
   }
 
   stop(): void {
@@ -69,10 +75,10 @@ export class TrellisState {
 /**
  * Factory function to create a TrellisState instance.
  */
-export async function createTrellisState<TApi extends TrellisAPI = TrellisAPI>(
+export async function createTrellisState<TApi extends TrellisAPI>(
   authState: AuthState,
   natsState: NatsState,
   config: TrellisStateConfig<TApi>,
-): Promise<TrellisState> {
-  return TrellisState.create(authState, natsState, config);
+): Promise<TrellisState<TApi>> {
+  return TrellisState.create<TApi>(authState, natsState, config);
 }