jazz-tools 0.19.19 → 0.19.21

package/src/svelte/auth/ClerkAuth.svelte.ts

@@ -0,0 +1,67 @@
+import { JazzClerkAuth, type MinimalClerkClient } from "jazz-tools";
+import { getAuthSecretStorage, getJazzContext } from "../jazz.svelte.js";
+import { useIsAuthenticated } from "./useIsAuthenticated.svelte.js";
+
+/**
+ * Authentication state returned by {@link useClerkAuth}.
+ *
+ * - `"anonymous"`: User is not authenticated with Jazz (may or may not be signed into Clerk)
+ * - `"signedIn"`: User is authenticated with both Clerk and Jazz
+ */
+export type ClerkAuth = {
+  state: "anonymous" | "signedIn";
+};
+
+/**
+ * Registers a Clerk authentication listener and provides reactive auth state.
+ *
+ * Must be used within a component that is a child of `JazzSvelteProvider`.
+ * Automatically syncs Clerk authentication state with Jazz.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClerkAuth } from "jazz-tools/svelte";
+ *
+ *   const auth = useClerkAuth(clerk);
+ * </script>
+ *
+ * {#if auth.state === "signedIn"}
+ *   <p>Welcome back!</p>
+ * {:else}
+ *   <p>Please sign in</p>
+ * {/if}
+ * ```
+ *
+ * @param clerk - The Clerk client instance
+ * @returns An object with a reactive `state` property
+ * @throws Error if used in guest mode
+ * @category Auth Providers
+ */
+export function useClerkAuth(clerk: MinimalClerkClient): ClerkAuth {
+  const context = getJazzContext();
+  const authSecretStorage = getAuthSecretStorage();
+
+  if ("guest" in context.current) {
+    throw new Error("Clerk auth is not supported in guest mode");
+  }
+
+  const authMethod = new JazzClerkAuth(
+    context.current.authenticate,
+    context.current.logOut,
+    authSecretStorage,
+  );
+
+  $effect(() => {
+    return authMethod.registerListener(clerk);
+  });
+
+  const isAuthenticated = useIsAuthenticated();
+  const state = $derived(isAuthenticated.current ? "signedIn" : "anonymous");
+
+  return {
+    get state() {
+      return state;
+    },
+  };
+}

package/src/svelte/auth/JazzSvelteProviderWithClerk.svelte

@@ -0,0 +1,156 @@
+<!--
+  @component
+  A pre-configured Jazz provider that integrates with Clerk authentication.
+
+  Use this component instead of `JazzSvelteProvider` when using Clerk for authentication.
+  It handles:
+  - Pre-loading Jazz credentials from Clerk before rendering children
+  - Registering Clerk auth state listeners
+  - Wiring up logout functionality to Clerk's signOut
+
+  @example
+  ```svelte
+  <JazzSvelteProviderWithClerk
+    {clerk}
+    sync={{ peer: "wss://cloud.jazz.tools/?key=your-key" }}
+    AccountSchema={MyAccountSchema}
+  >
+    <App />
+  </JazzSvelteProviderWithClerk>
+  ```
+
+  @category Auth Providers
+-->
+<script
+  lang="ts"
+  generics="S extends (AccountClass<Account> & CoValueFromRaw<Account>) | AnyAccountSchema"
+>
+  import {
+    Account,
+    type AccountClass,
+    type AnyAccountSchema,
+    type CoValueFromRaw,
+    InMemoryKVStore,
+    type InstanceOfSchema,
+    JazzClerkAuth,
+    KvStoreContext,
+    type MinimalClerkClient,
+    type SyncConfig,
+  } from "jazz-tools";
+  import {
+    type BaseBrowserContextOptions,
+    LocalStorageKVStore,
+  } from "jazz-tools/browser";
+  import type { Snippet } from "svelte";
+  import { JazzSvelteProvider } from "../jazz.svelte.js";
+  import RegisterClerkAuth from "./RegisterClerkAuth.svelte";
+
+  type Props = {
+    /** The Clerk client instance for authentication (can be null while Clerk is initializing) */
+    clerk: MinimalClerkClient | null;
+    /** Content to render when provider is initialized */
+    children?: Snippet;
+    /** Content to render while Clerk auth is loading */
+    fallback?: Snippet;
+    /** Content to render when authentication initialization fails */
+    errorFallback?: Snippet<[Error]>;
+    /** Callback when authentication initialization fails */
+    onAuthError?: (error: Error) => void;
+    /** Enable server-side rendering support with anonymous fallback */
+    enableSSR?: boolean;
+    /** Custom key for storing auth secrets in KvStore */
+    authSecretStorageKey?: string;
+    /** Jazz sync configuration (peer URL and key) */
+    sync: SyncConfig;
+    /** Custom storage implementation for auth secrets */
+    storage?: BaseBrowserContextOptions["storage"];
+    /** Account schema class for typed account access */
+    AccountSchema?: S;
+    /** Default profile name for new accounts */
+    defaultProfileName?: string;
+    /** Callback when an anonymous account is discarded during sign-in */
+    onAnonymousAccountDiscarded?: (
+      anonymousAccount: InstanceOfSchema<S>,
+    ) => Promise<void>;
+  };
+
+  let {
+    clerk,
+    children,
+    fallback,
+    errorFallback,
+    onAuthError,
+    ...providerProps
+  }: Props = $props();
+
+  let isLoaded = $state(false);
+  let initError = $state<Error | null>(null);
+
+  function setupKvStore() {
+    const isSSR = typeof window === "undefined";
+    if (isSSR) {
+      console.debug("[Jazz] Using InMemoryKVStore for SSR context");
+    }
+    KvStoreContext.getInstance().initialize(
+      isSSR ? new InMemoryKVStore() : new LocalStorageKVStore(),
+    );
+  }
+
+  /**
+   * Pre-loads Jazz authentication data from Clerk before mounting JazzSvelteProvider.
+   *
+   * For authenticated Clerk users with existing Jazz credentials, this populates the auth
+   * secret storage before rendering children, avoiding a flash of unauthenticated state.
+   * For unauthenticated users, the initialization completes immediately with no effect.
+   */
+  $effect(() => {
+    setupKvStore();
+
+    if (!clerk) return;
+
+    let cancelled = false;
+
+    JazzClerkAuth.initializeAuth(clerk)
+      .then(() => {
+        if (!cancelled) {
+          isLoaded = true;
+          initError = null;
+        }
+      })
+      .catch((error) => {
+        console.error(
+          "[Jazz] Clerk authentication initialization failed:",
+          error,
+        );
+        if (!cancelled) {
+          const errorObj =
+            error instanceof Error ? error : new Error(String(error));
+          initError = errorObj;
+          onAuthError?.(errorObj);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  });
+</script>
+
+{#if initError}
+  {#if errorFallback}
+    {@render errorFallback(initError)}
+  {:else}
+    <div data-testid="jazz-clerk-auth-error">
+      Authentication initialization failed. Please refresh the page or try again
+      later.
+    </div>
+  {/if}
+{:else if isLoaded && clerk}
+  <JazzSvelteProvider {...providerProps} onLogOut={clerk.signOut}>
+    <RegisterClerkAuth {clerk}>
+      {@render children?.()}
+    </RegisterClerkAuth>
+  </JazzSvelteProvider>
+{:else if fallback}
+  {@render fallback?.()}
+{/if}

package/src/svelte/auth/RegisterClerkAuth.svelte

@@ -0,0 +1,27 @@
+<!--
+  @component
+  Internal component that registers the Clerk auth listener.
+
+  This component exists because `useClerkAuth` requires access to the Jazz context,
+  which is only available inside `JazzSvelteProvider`'s children. By placing the
+  hook call in this child component, we ensure the context is properly initialized.
+-->
+<script lang="ts">
+  import type { MinimalClerkClient } from "jazz-tools";
+  import type { Snippet } from "svelte";
+  import { useClerkAuth } from "./ClerkAuth.svelte.js";
+
+  interface Props {
+    clerk: MinimalClerkClient;
+    children?: Snippet;
+  }
+
+  let { clerk, children }: Props = $props();
+
+  // Register the Clerk auth listener after JazzSvelteProvider context is available.
+  // The return value (auth state) is intentionally unused here - this component's
+  // sole purpose is to register the listener that syncs Clerk and Jazz auth state.
+  useClerkAuth(clerk);
+</script>
+
+{@render children?.()}

package/src/svelte/auth/index.ts

@@ -1,3 +1,5 @@
 export * from "./PasskeyAuth.svelte.js";
 export * from "./PassphraseAuth.svelte.js";
+export * from "./ClerkAuth.svelte.js";
 export { default as PasskeyAuthBasicUI } from "./PasskeyAuthBasicUI.svelte";
+export { default as JazzSvelteProviderWithClerk } from "./JazzSvelteProviderWithClerk.svelte";

package/src/svelte/tests/ClerkAuth.svelte.test.ts

@@ -0,0 +1,305 @@
+// @vitest-environment happy-dom
+
+import {
+  Account,
+  InMemoryKVStore,
+  JazzClerkAuth,
+  KvStoreContext,
+} from "jazz-tools";
+import type { MinimalClerkClient } from "jazz-tools";
+import { render as renderSvelte, waitFor } from "@testing-library/svelte";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createJazzTestAccount,
+  createJazzTestGuest,
+  setupJazzTestSync,
+} from "../testing";
+import { render, screen } from "./testUtils";
+import TestClerkAuthWrapper from "./TestClerkAuthWrapper.svelte";
+import JazzSvelteProviderWithClerk from "../auth/JazzSvelteProviderWithClerk.svelte";
+
+KvStoreContext.getInstance().initialize(new InMemoryKVStore());
+
+function createMockClerkClient(
+  user: MinimalClerkClient["user"] = null,
+): MinimalClerkClient {
+  return {
+    user,
+    signOut: vi.fn(),
+    addListener: vi.fn(() => () => {}),
+  };
+}
+
+describe("useClerkAuth", () => {
+  let account: Account;
+
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+  });
+
+  it("should return anonymous state when not authenticated", async () => {
+    const mockClerk = createMockClerkClient();
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(screen.getByTestId("auth-state").textContent).toBe("anonymous");
+  });
+
+  it("should return signedIn state when authenticated", async () => {
+    const mockClerk = createMockClerkClient({
+      id: "user_123",
+      fullName: "Test User",
+      username: "testuser",
+      firstName: "Test",
+      lastName: "User",
+      primaryEmailAddress: { emailAddress: "test@example.com" },
+      unsafeMetadata: {
+        jazzAccountID: "test123",
+        jazzAccountSecret: "secret123",
+      },
+      update: vi.fn(),
+    });
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: true },
+    );
+
+    expect(screen.getByTestId("auth-state").textContent).toBe("signedIn");
+  });
+
+  it("should register the clerk listener", async () => {
+    const mockClerk = createMockClerkClient();
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(mockClerk.addListener).toHaveBeenCalled();
+  });
+
+  it("should cleanup listener on unmount", async () => {
+    const mockUnsubscribe = vi.fn();
+    const mockClerk = createMockClerkClient();
+    mockClerk.addListener = vi.fn(() => mockUnsubscribe);
+
+    const { unmount } = render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(mockClerk.addListener).toHaveBeenCalled();
+    unmount();
+    expect(mockUnsubscribe).toHaveBeenCalled();
+  });
+
+  it("should throw error in guest mode", async () => {
+    const guest = await createJazzTestGuest();
+    const mockClerk = createMockClerkClient();
+
+    expect(() => {
+      render(TestClerkAuthWrapper, { clerk: mockClerk }, { account: guest });
+    }).toThrow("Clerk auth is not supported in guest mode");
+  });
+
+  it("should call listener with clerk client events", async () => {
+    const mockClerk = createMockClerkClient();
+    let listenerCallback: ((data: unknown) => void) | undefined;
+    mockClerk.addListener = vi.fn((callback) => {
+      listenerCallback = callback;
+      return () => {};
+    });
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(mockClerk.addListener).toHaveBeenCalled();
+    expect(listenerCallback).toBeDefined();
+  });
+});
+
+describe("JazzClerkAuth.initializeAuth", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should handle initialization errors gracefully", async () => {
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const initializeAuthSpy = vi
+      .spyOn(JazzClerkAuth, "initializeAuth")
+      .mockRejectedValue(new Error("Test error"));
+
+    const mockClerk = createMockClerkClient();
+
+    // The error should be thrown by the mock
+    await expect(JazzClerkAuth.initializeAuth(mockClerk)).rejects.toThrow(
+      "Test error",
+    );
+
+    // Restore using vitest's cleanup
+    initializeAuthSpy.mockRestore();
+    consoleSpy.mockRestore();
+  });
+});
+
+describe("JazzSvelteProviderWithClerk", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should render children after successful initialization", async () => {
+    const mockClerk = createMockClerkClient();
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockResolvedValue(undefined);
+
+    const { container } = renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+      },
+    });
+
+    await waitFor(() => {
+      // After initialization, the provider should render (even without children)
+      // The error div should not be present
+      expect(
+        container.querySelector('[data-testid="jazz-clerk-auth-error"]'),
+      ).toBeNull();
+    });
+  });
+
+  it("should show default error message when initialization fails", async () => {
+    const mockClerk = createMockClerkClient();
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockRejectedValue(
+      new Error("Init failed"),
+    );
+
+    const { container } = renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+      },
+    });
+
+    await waitFor(() => {
+      const errorDiv = container.querySelector(
+        '[data-testid="jazz-clerk-auth-error"]',
+      );
+      expect(errorDiv).not.toBeNull();
+      expect(errorDiv?.textContent).toContain(
+        "Authentication initialization failed",
+      );
+    });
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should call onAuthError callback when initialization fails", async () => {
+    const mockClerk = createMockClerkClient();
+    const onAuthError = vi.fn();
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockRejectedValue(
+      new Error("Init failed"),
+    );
+
+    renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+        onAuthError,
+      },
+    });
+
+    await waitFor(() => {
+      expect(onAuthError).toHaveBeenCalledWith(expect.any(Error));
+      expect(onAuthError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: "Init failed" }),
+      );
+    });
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should not update state after unmount (cancellation)", async () => {
+    const mockClerk = createMockClerkClient();
+    let resolveInit: () => void;
+    const initPromise = new Promise<void>((resolve) => {
+      resolveInit = resolve;
+    });
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockReturnValue(initPromise);
+
+    const { unmount } = renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+      },
+    });
+
+    // Unmount before initialization completes
+    unmount();
+
+    // Resolve the promise after unmount - should not cause errors
+    resolveInit!();
+
+    // Give time for any potential state updates
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // If we get here without errors, the cancellation worked
+    expect(true).toBe(true);
+  });
+});
+
+describe("useClerkAuth reactive state transitions", () => {
+  let account: Account;
+
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should update state reactively when listener callback fires", async () => {
+    const mockClerk = createMockClerkClient();
+    let listenerCallback: ((data: unknown) => void) | undefined;
+    mockClerk.addListener = vi.fn((callback) => {
+      listenerCallback = callback;
+      return () => {};
+    });
+
+    const { container } = render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    // Initial state should be anonymous
+    expect(screen.getByTestId("auth-state").textContent).toBe("anonymous");
+
+    // Verify listener was registered
+    expect(listenerCallback).toBeDefined();
+
+    // Note: Full state transition testing would require more complex setup
+    // involving the actual JazzClerkAuth.onClerkUserChange flow.
+    // This test verifies the listener registration which is the foundation
+    // for reactive updates.
+  });
+});

package/src/svelte/tests/TestClerkAuthWrapper.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import type { MinimalClerkClient } from "jazz-tools";
+  import { useClerkAuth } from "../auth/ClerkAuth.svelte.js";
+
+  type Props = {
+    clerk: MinimalClerkClient;
+  };
+
+  let { clerk }: Props = $props();
+
+  const auth = useClerkAuth(clerk);
+</script>
+
+<div data-testid="clerk-auth-wrapper">
+  <div data-testid="auth-state">{auth.state}</div>
+</div>

package/src/svelte/tests/testUtils.ts

@@ -6,6 +6,7 @@ import { JAZZ_AUTH_CTX, JAZZ_CTX } from "../jazz.svelte";
 
 type JazzExtendedOptions = {
   account: Account | { guest: AnonymousJazzAgent };
+  isAuthenticated?: boolean;
 };
 
 const render = <T extends Component>(
@@ -13,7 +14,9 @@ const render = <T extends Component>(
   props: ComponentProps<T>,
   jazzOptions: JazzExtendedOptions,
 ) => {
-  const ctx = TestJazzContextManager.fromAccountOrGuest(jazzOptions.account);
+  const ctx = TestJazzContextManager.fromAccountOrGuest(jazzOptions.account, {
+    isAuthenticated: jazzOptions.isAuthenticated,
+  });
 
   return renderSvelte(
     // @ts-expect-error Svelte new Component type is not compatible with @testing-library/svelte

package/src/tools/auth/clerk/types.ts

@@ -47,7 +47,7 @@ type PermissiveClerkUser = Omit<ClerkUser, "unsafeMetadata" | "update"> & {
 export type MinimalClerkClient = {
   user: PermissiveClerkUser | null | undefined;
   signOut: () => Promise<void>;
-  addListener: (listener: (data: unknown) => void) => void;
+  addListener: (listener: (data: unknown) => void) => (() => void) | void;
 };
 
 export type ClerkCredentials = {

package/src/tools/coValues/account.ts

@@ -271,7 +271,12 @@ export class Account extends CoValueBase implements CoValue {
     worker: Account,
     options: {
       creationProps: { name: string };
-      onCreate?: (account: A, worker: Account) => Promise<void>;
+      onCreate?: (
+        account: A,
+        worker: Account,
+        credentials: { accountID: string; accountSecret: AgentSecret },
+      ) => Promise<void>;
+      waitForSyncTimeout?: number;
     },
   ): Promise<{
     credentials: {
@@ -311,9 +316,12 @@ export class Account extends CoValueBase implements CoValue {
       throw new Error("Unable to load the worker account");
 
     // The onCreate hook can be helpful to define inline logic, such as querying the DB
-    if (options.onCreate) await options.onCreate(account, loadedWorker);
+    if (options.onCreate)
+      await options.onCreate(account, loadedWorker, credentials);
 
-    await account.$jazz.waitForAllCoValuesSync();
+    await account.$jazz.waitForAllCoValuesSync({
+      timeout: options.waitForSyncTimeout,
+    });
 
     const createdAccount = await this.load(account.$jazz.id, {
       loadAs: worker,

package/src/tools/implementation/zodSchema/schemaTypes/AccountSchema.ts

@@ -94,7 +94,31 @@ export class AccountSchema<
     );
   }
 
-  // Create an account via worker, useful to generate controlled accounts from the server
+  /**
+   * Creates a new account as a worker account, useful for generating controlled accounts from a server environment.
+   * This method initializes a new account, applies migrations, invokes the `onCreate` callback, and then shuts down the temporary node to avoid memory leaks.
+   * Returns the created account (loaded on the worker) and its credentials.
+   *
+   * The method internally calls `waitForAllCoValuesSync` on the new account. If many CoValues are created during `onCreate`,
+   * consider adjusting the timeout using the `waitForSyncTimeout` option.
+   *
+   * @param worker - The worker account to create the new account from
+   * @param options.creationProps - The creation properties for the new account
+   * @param options.onCreate - The callback to use to initialize the account after it is created
+   * @param options.waitForSyncTimeout - The timeout for the sync to complete
+   * @returns The credentials and the created account loaded by the worker account
+   *
+   *
+   * @example
+   * ```ts
+   * const { credentials, account } = await AccountSchema.createAs(worker, {
+   *   creationProps: { name: "My Account" },
+   *   onCreate: async (account, worker, credentials) => {
+   *     account.root.$jazz.owner.addMember(worker, "writer");
+   *   },
+   * });
+   * ```
+   */
   createAs(
     worker: Account,
     options: {
@@ -102,7 +126,9 @@ export class AccountSchema<
       onCreate?: (
         account: AccountInstance<Shape>,
         worker: Account,
+        credentials: { accountID: string; accountSecret: AgentSecret },
       ) => Promise<void>;
+      waitForSyncTimeout?: number;
     },
   ): Promise<{
     credentials: {

package/src/tools/subscribe/types.ts

@@ -49,4 +49,4 @@ export type SubscriptionValueLoading = {
   id: string;
 };
 
-export type BranchDefinition = { name: string; owner?: Group | Account | null };
+export type BranchDefinition = { name: string; owner?: Group | Account };