@hexclave/next 1.0.19 → 1.0.21

package/src/lib/hexclave-app/apps/implementations/client-app-impl.cross-domain.test.ts

@@ -273,6 +273,8 @@ describe("StackClientApp cross-domain auth", () => {
         protocol: "https:",
         hostname: "demo.stack-auth.com",
       },
+      addEventListener: () => {},
+      removeEventListener: () => {},
     } as any;
 
     const clientApp = new StackClientApp({
@@ -460,6 +462,40 @@ describe("StackClientApp cross-domain auth", () => {
     }
   });
 
+  it("throws when public app.urls reads would return hosted component URLs", () => {
+    const clientApp = new StackClientApp({
+      baseUrl: "http://localhost:12345",
+      projectId: "00000000-0000-4000-8000-000000000003",
+      publishableClientKey: "stack-pk-test",
+      tokenStore: "memory",
+      redirectMethod: "window",
+      urls: {
+        default: { type: "hosted" },
+      },
+      noAutomaticPrefetch: true,
+    });
+
+    expect(() => clientApp.urls.signIn).toThrowError(/app\.urls\.signIn cannot be used when this app is configured to use hosted components.*Use app\.redirectToSignIn\(\) instead/s);
+    expect(() => clientApp.urls.signOut).toThrowError(/app\.urls\.signOut cannot be used when this app is configured to use hosted components.*Use app\.redirectToSignOut\(\) instead/s);
+    expect(clientApp.urls.afterSignIn).toBe("/");
+  });
+
+  it("keeps public app.urls reads available for non-hosted targets", () => {
+    const clientApp = new StackClientApp({
+      baseUrl: "http://localhost:12345",
+      projectId: "00000000-0000-4000-8000-000000000003",
+      publishableClientKey: "stack-pk-test",
+      tokenStore: "memory",
+      redirectMethod: "window",
+      urls: {
+        handler: "/custom-handler",
+      },
+      noAutomaticPrefetch: true,
+    });
+
+    expect(clientApp.urls.signIn).toBe("/custom-handler/sign-in");
+  });
+
   it("keeps default hosted signOut() on the source domain when afterSignOut is not configured", async () => {
     const clientApp = new StackClientApp({
       baseUrl: "http://localhost:12345",

package/src/lib/hexclave-app/apps/implementations/client-app-impl.ts

@@ -93,6 +93,38 @@ const nestedCrossDomainAuthQueryParams = {
   afterCallbackRedirectUrl: "after_callback_redirect_url",
 } as const;
 
+function getRedirectHelperInstruction(handlerName: string): string {
+  if (handlerName === "handler") {
+    return "Use a page-specific redirect helper such as app.redirectToSignIn() instead.";
+  }
+  const redirectMethodName = `redirectTo${handlerName.slice(0, 1).toUpperCase()}${handlerName.slice(1)}`;
+  return `Use app.${redirectMethodName}() instead.`;
+}
+
+function createUrlsForPublicAccess(options: {
+  urls: ResolvedHandlerUrls,
+  projectId: string,
+}): Readonly<ResolvedHandlerUrls> {
+  const hostedUrlNames = new Set(
+    Object.entries(options.urls)
+      .filter(([, url]) => isHostedHandlerUrlForProject({ url, projectId: options.projectId }))
+      .map(([handlerName]) => handlerName),
+  );
+
+  return new Proxy(options.urls, {
+    get(target, property, receiver) {
+      if (typeof property === "string" && hostedUrlNames.has(property)) {
+        throw new Error(
+          `app.urls.${property} cannot be used when this app is configured to use hosted components. ` +
+          "`app.urls` is static and does not include the runtime redirect-back, cross-domain auth, or sign-out state required by hosted components. " +
+          getRedirectHelperInstruction(property),
+        );
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}
+
 const oauthCallbackResponseQueryParams = ["code", "state", "error", "error_description", "errorCode", "message", "details"] as const;
 
 const allClientApps = new Map<string, [checkString: string | undefined, app: StackClientApp<any, any>]>();
@@ -1688,7 +1720,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
           teamId: crud.id,
           email: options.email,
           session,
-          callbackUrl: options.callbackUrl ?? constructRedirectUrl(app.urls.teamInvitation, "callbackUrl"),
+          callbackUrl: options.callbackUrl ?? constructRedirectUrl(app._getUrls().teamInvitation, "callbackUrl"),
         });
         await app._teamInvitationsCache.refresh([session, crud.id]);
       },
@@ -1752,7 +1784,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       async sendVerificationEmail(options?: { callbackUrl?: string }) {
         await app._interface.sendCurrentUserContactChannelVerificationEmail(
           crud.id,
-          options?.callbackUrl || constructRedirectUrl(app.urls.emailVerification, "callbackUrl"),
+          options?.callbackUrl || constructRedirectUrl(app._getUrls().emailVerification, "callbackUrl"),
           session
         );
       },
@@ -2106,7 +2138,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
           {
             provider,
             redirectUrl: app._getOAuthCallbackRedirectUri(),
-            errorRedirectUrl: app.urls.error,
+            errorRedirectUrl: app._getUrls().error,
             providerScope: mergeScopeStrings(scopeString, (app._oauthScopesOnSignIn[provider as ProviderType] ?? []).join(" ")),
           },
           session,
@@ -2235,7 +2267,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         }
         return await app._interface.sendVerificationEmail(
           crud.primary_email,
-          options?.callbackUrl ?? constructRedirectUrl(app.urls.emailVerification, "callbackUrl"),
+          options?.callbackUrl ?? constructRedirectUrl(app._getUrls().emailVerification, "callbackUrl"),
           session
         );
       },
@@ -2690,6 +2722,13 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
   }
 
   get urls(): Readonly<ResolvedHandlerUrls> {
+    return createUrlsForPublicAccess({
+      urls: this._getUrls(),
+      projectId: this.projectId,
+    });
+  }
+
+  protected _getUrls(): Readonly<ResolvedHandlerUrls> {
     return getUrls(this._urlOptions, { projectId: this.projectId });
   }
 

package/src/lib/hexclave-app/apps/implementations/event-tracker.test.ts

@@ -4,6 +4,7 @@
 //===========================================
 // @vitest-environment jsdom
 
+import { KnownErrors } from "@hexclave/shared/dist/known-errors";
 import { Result } from "@hexclave/shared/dist/utils/results";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { EventTracker } from "./event-tracker";
@@ -390,7 +391,7 @@ describe("EventTracker", () => {
     }
   });
 
-  it("silently disables when server responds with ANALYTICS_NOT_ENABLED", async () => {
+  it("silently disables when client interface returns ANALYTICS_NOT_ENABLED as an error", async () => {
     vi.useFakeTimers();
     document.body.innerHTML = "<button>Click me</button>";
 
@@ -400,28 +401,19 @@ describe("EventTracker", () => {
       projectId: "internal",
       sendBatch: async (body) => {
         sentBodies.push(body);
-        return Result.ok(new Response(
-          JSON.stringify({ code: "ANALYTICS_NOT_ENABLED", error: "Analytics is not enabled for this project." }),
-          {
-            status: 400,
-            headers: { "x-stack-known-error": "ANALYTICS_NOT_ENABLED" },
-          },
-        ));
+        return Result.error(new KnownErrors.AnalyticsNotEnabled());
       },
     });
 
     try {
       tracker.start();
 
-      // First flush sends the initial page-view event; server rejects it.
       await advancePastFlush();
       expect(sentBodies).toHaveLength(1);
-
-      // No console.warn should have been emitted.
       expect(warnSpy).not.toHaveBeenCalled();
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      expect((tracker as any)._flushTimer).toBeNull();
 
-      // After disabling, new events should not accumulate or trigger further
-      // flushes.
       document.querySelector("button")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
       await advancePastFlush();
       expect(sentBodies).toHaveLength(1);

package/src/lib/hexclave-app/apps/implementations/event-tracker.ts

@@ -8,7 +8,7 @@ import { cssEscapeIdent } from "@hexclave/shared/dist/utils/dom";
 import { buildElementsChain, ELEMENTS_CHAIN_MAX_DEPTH } from "@hexclave/shared/dist/utils/elements-chain";
 import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
 import { Result } from "@hexclave/shared/dist/utils/results";
-import { generateUuid } from "./session-replay";
+import { generateUuid, isAnalyticsNotEnabledError } from "./session-replay";
 
 const FLUSH_INTERVAL_MS = 10_000;
 const MAX_EVENTS_PER_BATCH = 50;
@@ -34,6 +34,10 @@ function hasHistoryMethods(value: unknown): value is { pushState: History["pushS
   return typeof value.pushState === "function" && typeof value.replaceState === "function";
 }
 
+function getTextSnippet(textContent: string | null): string {
+  return textContent == null ? "" : textContent.trim().substring(0, 200);
+}
+
 // Pixel quantization factor for x/y/viewport in stored click events. Matches the
 // SCALE_FACTOR used by the ClickHouse clickmap_events MV — keep them in sync.
 const CLICKMAP_SCALE_FACTOR = 16;
@@ -321,7 +325,7 @@ export class EventTracker {
       event_at_ms: Date.now(),
       data: {
         tag_name: target.tagName.toLowerCase(),
-        text: target.textContent.trim().substring(0, 200),
+        text: getTextSnippet(target.textContent),
         href: this._findNearestAnchorHref(target),
         selector: this._buildSelector(target),
         elements_chain: buildElementsChain(target),
@@ -503,27 +507,28 @@ export class EventTracker {
     );
 
     if (res.status === "error") {
+      if (isAnalyticsNotEnabledError(res.error)) {
+        this._disable();
+        return;
+      }
       console.warn("EventTracker flush failed:", res.error);
       return;
     }
 
     if (!res.data.ok) {
-      // If the server tells us analytics is not enabled for this project,
-      // silently disable the tracker — no point retrying or warning the user.
-      const knownError = res.data.headers.get("x-hexclave-known-error") ?? res.data.headers.get("x-stack-known-error");
-      if (knownError === "ANALYTICS_NOT_ENABLED") {
-        this._disabled = true;
-        if (this._flushTimer !== null) {
-          clearInterval(this._flushTimer);
-          this._flushTimer = null;
-        }
-        this._teardown();
-        return;
-      }
       console.warn("EventTracker flush failed:", res.data.status, await res.data.text());
     }
   }
 
+  private _disable() {
+    this._disabled = true;
+    if (this._flushTimer !== null) {
+      clearInterval(this._flushTimer);
+      this._flushTimer = null;
+    }
+    this._teardown();
+  }
+
   private _tick() {
     if (this._cancelled) return;
     if (this._events.length > 0) {

package/src/lib/hexclave-app/apps/implementations/server-app-impl.ts

@@ -362,7 +362,7 @@ export class _HexclaveServerAppImplIncomplete<HasTokenStore extends boolean, Pro
       isPrimary: crud.is_primary,
       usedForAuth: crud.used_for_auth,
       async sendVerificationEmail(options?: { callbackUrl?: string }) {
-        await app._interface.sendServerContactChannelVerificationEmail(userId, crud.id, options?.callbackUrl ?? constructRedirectUrl(app.urls.emailVerification, "callbackUrl"));
+        await app._interface.sendServerContactChannelVerificationEmail(userId, crud.id, options?.callbackUrl ?? constructRedirectUrl(app._getUrls().emailVerification, "callbackUrl"));
       },
       async update(data: ServerContactChannelUpdateOptions) {
         await app._interface.updateServerContactChannel(userId, crud.id, serverContactChannelUpdateOptionsToCrud(data));
@@ -1042,7 +1042,7 @@ export class _HexclaveServerAppImplIncomplete<HasTokenStore extends boolean, Pro
         await app._interface.sendServerTeamInvitation({
           teamId: crud.id,
           email: options.email,
-          callbackUrl: options.callbackUrl ?? constructRedirectUrl(app.urls.teamInvitation, "callbackUrl"),
+          callbackUrl: options.callbackUrl ?? constructRedirectUrl(app._getUrls().teamInvitation, "callbackUrl"),
         });
         await app._serverTeamInvitationsCache.refresh([crud.id]);
       },

package/src/lib/hexclave-app/apps/implementations/session-replay.test.ts

@@ -4,6 +4,7 @@
 //===========================================
 // @vitest-environment jsdom
 
+import { KnownErrors } from "@hexclave/shared/dist/known-errors";
 import { describe, expect, it, vi } from "vitest";
 import { Result } from "@hexclave/shared/dist/utils/results";
 import { analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions, SessionRecorder } from "./session-replay";
@@ -48,10 +49,9 @@ describe("analytics option JSON conversion", () => {
 });
 
 describe("SessionRecorder flush", () => {
-  it("silently disables when server responds with ANALYTICS_NOT_ENABLED", async () => {
+  it("silently disables when client interface returns ANALYTICS_NOT_ENABLED as an error", async () => {
     vi.useFakeTimers();
 
-    // Seed localStorage with a valid session so _flush doesn't fail on getOrRotateSession
     const storageKey = `hexclave:session-replay:v1:test-project`;
     localStorage.setItem(storageKey, JSON.stringify({
       session_id: "test-session",
@@ -65,13 +65,7 @@ describe("SessionRecorder flush", () => {
         projectId: "test-project",
         sendBatch: async (body) => {
           sentBodies.push(body);
-          return Result.ok(new Response(
-            JSON.stringify({ code: "ANALYTICS_NOT_ENABLED", error: "Analytics is not enabled for this project." }),
-            {
-              status: 400,
-              headers: { "x-stack-known-error": "ANALYTICS_NOT_ENABLED" },
-            },
-          ));
+          return Result.error(new KnownErrors.AnalyticsNotEnabled());
         },
       },
       {},
@@ -80,26 +74,16 @@ describe("SessionRecorder flush", () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
 
     try {
-      // Inject an event directly into the recorder's buffer to test flush behavior
-      // without needing rrweb. We access private fields for testing purposes.
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
       (recorder as any)._events = [{ type: 2, timestamp: Date.now(), data: {} }];
 
-      // Manually trigger a tick (which calls _flush)
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
       (recorder as any)._tick();
       await vi.advanceTimersByTimeAsync(0);
 
-      // One batch should have been sent
       expect(sentBodies).toHaveLength(1);
+      expect(warnSpy).not.toHaveBeenCalled();
 
-      // No console.warn about "SessionRecorder flush failed" should have been emitted
-      const flushWarnings = warnSpy.mock.calls.filter(
-        (args) => typeof args[0] === "string" && args[0].includes("SessionRecorder")
-      );
-      expect(flushWarnings).toHaveLength(0);
-
-      // After disabling, pushing new events and triggering another tick should not send
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
       (recorder as any)._events = [{ type: 3, timestamp: Date.now(), data: {} }];
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call

package/src/lib/hexclave-app/apps/implementations/session-replay.ts

@@ -2,6 +2,7 @@
 //===========================================
 // THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
 //===========================================
+import { KnownErrors } from "@hexclave/shared/dist/known-errors";
 import { isBrowserLike } from "@hexclave/shared/dist/utils/env";
 import { captureWarning } from "@hexclave/shared/dist/utils/errors";
 import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
@@ -165,6 +166,10 @@ export type SessionRecorderDeps = {
   sendBatch: (body: string, options: { keepalive: boolean }) => Promise<Result<Response, Error>>,
 };
 
+export function isAnalyticsNotEnabledError(error: unknown): boolean {
+  return KnownErrors.AnalyticsNotEnabled.isInstance(error);
+}
+
 export class SessionRecorder {
   private _started = false;
   private _cancelled = false;
@@ -269,23 +274,15 @@ export class SessionRecorder {
       );
 
       if (res.status === "error") {
+        if (isAnalyticsNotEnabledError(res.error)) {
+          this._disable();
+          return;
+        }
         captureWarning("SessionRecorder.flush", res.error);
         return;
       }
 
       if (!res.data.ok) {
-        // If the server tells us analytics is not enabled for this project,
-        // silently disable the recorder — no point retrying or warning the user.
-        const knownError = res.data.headers.get("x-hexclave-known-error") ?? res.data.headers.get("x-stack-known-error");
-        if (knownError === "ANALYTICS_NOT_ENABLED") {
-          this._disabled = true;
-          if (this._flushTimer !== null) {
-            clearInterval(this._flushTimer);
-            this._flushTimer = null;
-          }
-          this._stopCurrentRecording();
-          return;
-        }
         captureWarning("SessionRecorder.flush", new Error(`SessionRecorder flush failed: ${res.data.status} ${await res.data.text()}`));
       }
     } finally {
@@ -293,6 +290,16 @@ export class SessionRecorder {
     }
   }
 
+  private _disable() {
+    this._disabled = true;
+    this.clearBuffer();
+    if (this._flushTimer !== null) {
+      clearInterval(this._flushTimer);
+      this._flushTimer = null;
+    }
+    this._stopCurrentRecording();
+  }
+
   private async _startRecording() {
     if (this._recording || this._cancelled) return;
 

package/src/lib/hexclave-app/apps/interfaces/client-app.ts

@@ -68,8 +68,9 @@ export type StackClientApp<HasTokenStore extends boolean = boolean, ProjectId ex
     readonly version: string,
 
     /**
-     * @deprecated `app.urls` is static and does not include runtime redirect-back parameters.
-     * For navigation, prefer `redirectToXyz()` methods (for example `redirectToSignIn()`).
+     * @deprecated Do not use `app.urls` for navigation. It is static and does not include runtime redirect-back,
+     * cross-domain auth, or sign-out state. Use the matching `redirectToXyz()` method instead, for example
+     * `redirectToSignIn()`, `redirectToSignUp()`, `redirectToSignOut()`, or `redirectToAccountSettings()`.
      */
     readonly urls: Readonly<ResolvedHandlerUrls>,
 

package/src/lib/hexclave-app/project-configs/index.ts

@@ -76,6 +76,14 @@ export type AdminOAuthProviderConfig = {
       microsoftTenantId?: string,
       appleBundleIds?: string[],
     }
+    | {
+      type: 'custom_oidc',
+      clientId: string,
+      clientSecret: string,
+      issuerUrl: string,
+      scope?: string,
+      displayName?: string,
+    }
   ) & OAuthProviderConfig;
 
 export type AdminProjectConfigUpdateOptions = {

package/src/lib/hexclave-app/projects/index.ts

@@ -178,17 +178,19 @@ export function adminProjectUpdateOptionsToCrud(options: AdminProjectUpdateOptio
         domain: d.domain,
         handler_path: d.handlerPath
       })),
-      oauth_providers: options.config?.oauthProviders?.map((p) => ({
-        id: p.id as any,
-        type: p.type,
-        ...(p.type === 'standard' && {
-          client_id: p.clientId,
-          client_secret: p.clientSecret,
-          facebook_config_id: p.facebookConfigId,
-          microsoft_tenant_id: p.microsoftTenantId,
-          apple_bundle_ids: p.appleBundleIds,
-        }),
-      })),
+      oauth_providers: options.config?.oauthProviders
+        ?.filter((p): p is Exclude<typeof p, { type: 'custom_oidc' }> => p.type !== 'custom_oidc')
+        .map((p) => ({
+          id: p.id as any,
+          type: p.type,
+          ...(p.type === 'standard' && {
+            client_id: p.clientId,
+            client_secret: p.clientSecret,
+            facebook_config_id: p.facebookConfigId,
+            microsoft_tenant_id: p.microsoftTenantId,
+            apple_bundle_ids: p.appleBundleIds,
+          }),
+        })),
       email_config: options.config?.emailConfig && (
         options.config.emailConfig.type === 'shared' ? {
           type: 'shared',