@qlever-llc/trellis-svelte 0.4.0 → 0.5.1

package/README.md

@@ -4,4 +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.
 
-Uses the contract/runtime model from `@qlever-llc/trellis-contracts` and `@qlever-llc/trellis-trellis`.
+Prefer `getTrellisFor(contract)` in app code so the client stays typed from the same contract passed to `TrellisProvider`.
+
+Uses the contract/runtime model from `@qlever-llc/trellis-contracts` and `@qlever-llc/trellis`.

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@qlever-llc/trellis-svelte",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Svelte components and state helpers for Trellis browser applications.",
   "license": "Apache-2.0",
+  "homepage": "https://github.com/Qlever-LLC/trellis#readme",
+  "bugs": {
+    "url": "https://github.com/Qlever-LLC/trellis/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Qlever-LLC/trellis"
+  },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "files": [
     "src",
@@ -20,11 +28,11 @@
   },
   "dependencies": {
     "@nats-io/nats-core": "^3.3.1",
-    "@qlever-llc/trellis-auth": "^0.4.0",
-    "@qlever-llc/trellis-contracts": "^0.4.0",
-    "@qlever-llc/trellis-result": "^0.4.0",
-    "@qlever-llc/trellis-sdk-auth": "^0.4.0",
-    "@qlever-llc/trellis-trellis": "^0.4.0",
+    "@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",
     "typebox": "^1.0.15"
   },
   "peerDependencies": {

package/src/components/TrellisProvider.svelte

@@ -8,7 +8,7 @@
     setNatsStateContext,
     setTrellisContext,
   } from "../context.svelte.ts";
-  import { type AuthState, createAuthState } from "../state/auth.svelte.ts";
+  import { type AuthState, type AuthStateConfig, type BindErrorResult, createAuthState } from "../state/auth.svelte.ts";
   import { createNatsState, type NatsState } from "../state/nats.svelte.ts";
   import {
     createTrellisState,
@@ -27,6 +27,7 @@
     onAuthExpired?: () => void;
     onAuthFailed?: (error: unknown) => void;
     onAuthRequired?: (redirectTo: string) => void;
+    onBindError?: (result: BindErrorResult) => void;
     onNatsConnecting?: () => void;
     onNatsConnected?: () => void;
     onNatsDisconnect?: () => void;
@@ -46,6 +47,7 @@
     onAuthExpired,
     onAuthFailed,
     onAuthRequired,
+    onBindError,
     onNatsConnecting,
     onNatsConnected,
     onNatsDisconnect,
@@ -66,12 +68,20 @@
     }
   }
 
+  class BindFailedError extends Error {
+    constructor() {
+      super("Bind failed");
+    }
+  }
+
   function createProviderAuthState(): AuthState {
-    return createAuthState({
+    const config: AuthStateConfig = {
       authUrl,
       loginPath,
       contract,
-    });
+    };
+
+    return createAuthState(config);
   }
 
   const authState = createProviderAuthState();
@@ -87,16 +97,22 @@
   async function initialize(): Promise<InitContext> {
     const result = await AsyncResult.try(async () => {
       await authState.init();
-      await authState.handleCallback();
+      const bindResult = await authState.handleCallback();
       authState.cleanupCallbackUrl();
 
+      if (bindResult !== null && bindResult.status !== "bound") {
+        onBindError?.(bindResult);
+        throw new BindFailedError();
+      }
+
       if (!authState.isAuthenticated) {
         onAuthRequired?.(getRedirectTo());
         throw new AuthRequiredError();
       }
 
+      const effectiveNatsServers = authState.natsServers ?? natsServers;
       const natsState = await createNatsState(authState, {
-        servers: natsServers,
+        servers: effectiveNatsServers,
         onConnecting: onNatsConnecting,
         onConnected: onNatsConnected,
         onDisconnect: onNatsDisconnect,
@@ -121,11 +137,12 @@
     });
 
     if (result.isErr()) {
-      authState.clearAuth();
       const error = result.error;
-      if (!(error instanceof AuthRequiredError)) {
-        onAuthFailed?.(error);
+      if (error instanceof AuthRequiredError || error instanceof BindFailedError) {
+        throw error;
       }
+      authState.clearAuth();
+      onAuthFailed?.(error);
       throw error;
     }
 

package/src/context.svelte.ts

@@ -1,7 +1,7 @@
-import { getContext, setContext } from "svelte";
-import type { TrellisAPI } from "@qlever-llc/trellis-contracts";
-import type { Trellis } from "@qlever-llc/trellis-trellis";
 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 { NatsState } from "./state/nats.svelte.ts";
 
@@ -15,6 +15,35 @@ type TrellisContext = {
   nats: Promise<NatsConnection>;
 };
 
+type TrellisContractLike<TA extends TrellisAPI = TrellisAPI> = {
+  API: {
+    trellis: TA;
+  };
+};
+
+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>(
+    method: M,
+    input: RpcMapFor<TA>[M]["input"],
+    opts?: RequestOpts,
+  ): Promise<RpcMapFor<TA>[M]["output"]>;
+};
+
+type TypedTrellis<TA extends TrellisAPI> =
+  & Omit<Trellis<TA>, "requestOrThrow">
+  & TypedRequestSurface<TA>;
+
 export function setTrellisContext<TA extends TrellisAPI>(
   ctx: { trellis: Promise<Trellis<TA>>; nats: Promise<NatsConnection> },
 ): void {
@@ -34,6 +63,14 @@ export function getTrellis<TA extends TrellisAPI = TrellisAPI>(): Promise<Trelli
   return getContext<Promise<unknown>>(TRELLIS_KEY) as Promise<Trellis<TA>>;
 }
 
+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 getNats(): Promise<NatsConnection> {
   return getContext<Promise<NatsConnection>>(NATS_KEY);
 }

package/src/index.ts

@@ -1,6 +1,6 @@
 export { default as TrellisProvider } from "./components/TrellisProvider.svelte";
-export { setTrellisContext, getTrellis, getNats, getNatsState, getAuth } from "./context.svelte.ts";
-export { AuthState, createAuthState } from "./state/auth.svelte.ts";
-export { NatsState, createNatsState } from "./state/nats.svelte.ts";
-export type { Status as NatsStatus, NatsStateConfig } from "./state/nats.svelte.ts";
-export { TrellisState, createTrellisState } from "./state/trellis.svelte.ts";
+export { getAuth, getNats, getNatsState, getTrellis, getTrellisFor, setTrellisContext } from "./context.svelte.ts";
+export { AuthState, type BindErrorResult, type BindResult, createAuthState } 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 { createTrellisState, TrellisState } from "./state/trellis.svelte.ts";

package/src/state/auth.svelte.ts

@@ -4,6 +4,7 @@ import {
   bindSession,
   buildLoginUrl,
   clearSessionKey,
+  extractAuthErrorFromFragment,
   extractAuthTokenFromFragment,
   getOrCreateSessionKey,
   getPublicSessionKey,
@@ -15,6 +16,22 @@ import { SvelteDate } from "svelte/reactivity";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+export type BindErrorResult =
+  | { status: "insufficient_capabilities"; missingCapabilities: string[] }
+  | { status: "approval_required" }
+  | { status: "approval_denied" }
+  | { status: "error"; message: string };
+
+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";
 
 type AuthStateData = {
@@ -23,6 +40,7 @@ type AuthStateData = {
   inboxPrefix: string | null;
   expiresMs: number | null;
   sentinel: SentinelCreds | null;
+  natsServers: string[] | null;
 };
 
 type PersistedAuth = {
@@ -30,6 +48,7 @@ type PersistedAuth = {
   inboxPrefix: string;
   expires: string;
   sentinel: SentinelCreds;
+  natsServers: string[];
 };
 
 const PersistedAuthSchema = Type.Object({
@@ -40,6 +59,7 @@ const PersistedAuthSchema = Type.Object({
     jwt: Type.String(),
     seed: Type.String(),
   }, { additionalProperties: false }),
+  natsServers: Type.Array(Type.String()),
 }, { additionalProperties: false });
 
 function loadPersistedAuth(): PersistedAuth | null {
@@ -63,16 +83,18 @@ function persistAuth(state: {
   expires: Date;
   inboxPrefix: string;
   sentinel: SentinelCreds;
+  natsServers: string[];
 }): void {
   if (typeof localStorage === "undefined") return;
   localStorage.setItem(
     STORAGE_KEY,
     JSON.stringify({
-      bindingToken: state.bindingToken,
-      inboxPrefix: state.inboxPrefix,
-      expires: state.expires.toISOString(),
-      sentinel: state.sentinel,
-    }),
+        bindingToken: state.bindingToken,
+        inboxPrefix: state.inboxPrefix,
+        expires: state.expires.toISOString(),
+        sentinel: state.sentinel,
+        natsServers: state.natsServers,
+      }),
   );
 }
 
@@ -84,7 +106,7 @@ function clearPersistedAuth(): void {
 export type AuthStateConfig = {
   authUrl: string; // https://auth.example.com
   loginPath?: string;
-  contract: { CONTRACT: Record<string, unknown> };
+  contract?: { CONTRACT: Record<string, unknown> };
 };
 
 /**
@@ -103,10 +125,11 @@ export class AuthState {
     inboxPrefix: null,
     expiresMs: null,
     sentinel: null,
+    natsServers: null,
   });
 
   #config: AuthStateConfig;
-  #bindingInProgress: Promise<BindResponse> | null = null;
+  #bindingInProgress: Promise<BindResult> | null = null;
 
   constructor(config: AuthStateConfig) {
     this.#config = config;
@@ -130,6 +153,9 @@ export class AuthState {
   get sentinel(): SentinelCreds | null {
     return this.#state.sentinel;
   }
+  get natsServers(): string[] | null {
+    return this.#state.natsServers;
+  }
   get isAuthenticated(): boolean {
     if (!this.#state.bindingToken) return false;
     if (this.#state.expiresMs === null) return false;
@@ -152,6 +178,7 @@ export class AuthState {
       this.#state.inboxPrefix = persisted.inboxPrefix;
       this.#state.expiresMs = Date.parse(persisted.expires);
       this.#state.sentinel = persisted.sentinel;
+      this.#state.natsServers = persisted.natsServers;
     }
 
     return handle;
@@ -161,34 +188,30 @@ 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, redirectTo: string): Promise<never> {
+  async signIn(provider: string | undefined, redirectTo: string): Promise<never> {
     const handle = await this.init();
-    const url = await buildLoginUrl(
+    const url = await buildLoginHref(
       { authUrl: this.#config.authUrl },
       provider,
       redirectTo,
       handle,
-      this.#config.contract.CONTRACT,
+      this.#config.contract?.CONTRACT ?? {},
     );
     window.location.href = url;
-    throw new Error(`Redirecting to ${provider} for authentication`);
+    throw new Error(provider ? `Redirecting to ${provider} for authentication` : "Redirecting to auth for provider selection");
   }
 
-  /**
-   * Handle OAuth callback by extracting the authToken from the URL fragment
-   * and binding it to the session key.
-   *
-   * Returns the bind response if a fragment exists, null otherwise.
-   * Includes a guard to prevent double binding when multiple components call this.
-   */
-  async handleCallback(url: string = window.location.href): Promise<BindResponse | null> {
-    // Guard to prevent race conditions when multiple components call handleCallback
+  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;
 
-    this.#bindingInProgress = this.bind(authToken);
+    this.#bindingInProgress = this.#resolveCallback(authToken);
     try {
       return await this.#bindingInProgress;
     } finally {
@@ -196,6 +219,20 @@ export class AuthState {
     }
   }
 
+  async #resolveCallback(authToken: string): Promise<BindResult> {
+    try {
+      const response = await this.bind(authToken);
+      return response.status === "bound"
+        ? { status: "bound" }
+        : { status: "insufficient_capabilities", missingCapabilities: response.missingCapabilities };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("approval_denied")) return { status: "approval_denied" };
+      if (message.includes("approval_required")) return { status: "approval_required" };
+      return { status: "error", message };
+    }
+  }
+
   /**
    * Clean up the callback URL by removing the authToken fragment.
    */
@@ -233,6 +270,7 @@ export class AuthState {
   setBindingToken(
     response: Pick<BindSuccessResponse, "bindingToken" | "inboxPrefix" | "expires"> & {
       sentinel?: SentinelCreds;
+      natsServers?: string[];
     },
   ): void {
     this.#state.bindingToken = response.bindingToken;
@@ -242,14 +280,18 @@ export class AuthState {
     if (response.sentinel) {
       this.#state.sentinel = response.sentinel;
     }
+    if (response.natsServers) {
+      this.#state.natsServers = response.natsServers;
+    }
 
     // Only persist if we have sentinel credentials
-    if (this.#state.sentinel) {
+    if (this.#state.sentinel && this.#state.natsServers) {
       persistAuth({
         bindingToken: response.bindingToken,
         inboxPrefix: response.inboxPrefix,
         expires: new SvelteDate(String(response.expires)),
         sentinel: this.#state.sentinel,
+        natsServers: this.#state.natsServers,
       });
     }
   }
@@ -264,6 +306,7 @@ export class AuthState {
     this.#state.inboxPrefix = null;
     this.#state.expiresMs = null;
     this.#state.sentinel = null;
+    this.#state.natsServers = null;
   }
 
   /**

package/src/state/nats.svelte.ts

@@ -3,6 +3,7 @@ import {
   type NatsConnection,
   wsconnect,
 } from "@nats-io/nats-core";
+import { createClient } from "@qlever-llc/trellis";
 import {
   getPublicSessionKey,
   natsConnectSigForBindingToken,
@@ -16,7 +17,6 @@ import {
   type AuthRenewBindingTokenInput,
   type AuthRenewBindingTokenOutput,
 } from "@qlever-llc/trellis-sdk-auth";
-import { createClient } from "@qlever-llc/trellis-trellis";
 import type { AuthState } from "./auth.svelte.ts";
 
 const AUTH_RENEW_API = {

package/src/state/trellis.svelte.ts

@@ -1,7 +1,7 @@
 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 { type ClientOpts, createClient, type Trellis, type TrellisAuth } from "@qlever-llc/trellis-trellis";
 import type { AuthState } from "./auth.svelte.ts";
 import type { NatsState } from "./nats.svelte.ts";