@hexclave/js 1.0.18 → 1.0.20

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

@@ -65,7 +65,7 @@ import { EventTracker } from "./event-tracker";
 import type { CrossDomainHandoffParams } from "./redirect-page-urls";
 import { crossDomainAuthQueryParams, getCrossDomainHandoffParamsFromCurrentUrl, planRedirectToHandler } from "./redirect-page-urls";
 import { subscribeSessionRefresh } from "./session-refresh-subscription";
-import { AnalyticsOptions, SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson } from "./session-replay";
+import { AnalyticsOptions, SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions } from "./session-replay";
 
 import { mountClickmapOverlay } from "../../../../clickmap";
 import { mountDevTool } from "../../../../dev-tool";
@@ -84,6 +84,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>]>();
@@ -629,13 +661,14 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
 
     const analyticsEnabled = this._analyticsOptions?.enabled !== false;
 
-    if (analyticsEnabled && isBrowserLike() && this._hasPersistentTokenStore() && this._analyticsOptions?.replays?.enabled === true) {
+    const sessionReplayOptions = getSessionReplayOptions(this._analyticsOptions);
+    if (analyticsEnabled && isBrowserLike() && this._hasPersistentTokenStore() && sessionReplayOptions.enabled) {
       this._sessionRecorder = new SessionRecorder({
         projectId: this.projectId,
         sendBatch: async (body, opts) => {
           return await this._interface.sendSessionReplayBatch(body, await getAnalyticsSession(), opts);
         },
-      }, this._analyticsOptions.replays);
+      }, sessionReplayOptions);
       this._sessionRecorder.start();
     }
 
@@ -1629,7 +1662,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]);
       },
@@ -1681,7 +1714,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
         );
       },
@@ -1958,7 +1991,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,
@@ -2045,7 +2078,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
         );
       },
@@ -2436,6 +2469,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

@@ -389,4 +389,45 @@ describe("EventTracker", () => {
       tracker.stop();
     }
   });
+
+  it("silently disables when server responds with ANALYTICS_NOT_ENABLED", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = "<button>Click me</button>";
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const sentBodies: string[] = [];
+    const tracker = new 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" },
+          },
+        ));
+      },
+    });
+
+    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();
+
+      // 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);
+    } finally {
+      tracker.stop();
+      warnSpy.mockRestore();
+    }
+  });
 });

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

@@ -112,6 +112,7 @@ type TrackedEvent = {
 export class EventTracker {
   private _started = false;
   private _cancelled = false;
+  private _disabled = false;
   private _detachListeners: (() => void) | null = null;
   private _flushTimer: ReturnType<typeof setInterval> | null = null;
   private _events: TrackedEvent[] = [];
@@ -177,6 +178,7 @@ export class EventTracker {
   }
 
   private _pushEvent(event: TrackedEvent) {
+    if (this._disabled) return;
     this._events.push(event);
     this._approxBytes += JSON.stringify(event).length;
     if (this._events.length >= MAX_EVENTS_PER_BATCH || this._approxBytes >= MAX_APPROX_BYTES_PER_BATCH) {
@@ -468,6 +470,8 @@ export class EventTracker {
   }
 
   private async _flush(options: { keepalive: boolean }) {
+    if (this._disabled) return;
+
     // A keepalive flush means the page is unloading — a click still awaiting
     // dead-click classification led to that unload, so it is alive by
     // definition and ships unmarked.
@@ -504,6 +508,18 @@ export class EventTracker {
     }
 
     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());
     }
   }

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

@@ -356,7 +356,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));
@@ -922,7 +922,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

@@ -2,8 +2,23 @@
 //===========================================
 // THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
 //===========================================
-import { describe, expect, it } from "vitest";
-import { analyticsOptionsFromJson, analyticsOptionsToJson } from "./session-replay";
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions, SessionRecorder } from "./session-replay";
+
+describe("session replay options", () => {
+  it("enables replays by default", () => {
+    expect(getSessionReplayOptions(undefined).enabled).toBe(true);
+    expect(getSessionReplayOptions({}).enabled).toBe(true);
+    expect(getSessionReplayOptions({ replays: {} }).enabled).toBe(true);
+  });
+
+  it("preserves explicit replay opt-out", () => {
+    expect(getSessionReplayOptions({ replays: { enabled: false } }).enabled).toBe(false);
+  });
+});
 
 describe("analytics option JSON conversion", () => {
   it("preserves top-level analytics options when serializing replay block classes", () => {
@@ -31,3 +46,71 @@ describe("analytics option JSON conversion", () => {
     expect(roundTripped?.replays?.blockClass).toEqual(/stack-sensitive/u);
   });
 });
+
+describe("SessionRecorder flush", () => {
+  it("silently disables when server responds with ANALYTICS_NOT_ENABLED", 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",
+      created_at_ms: Date.now(),
+      last_activity_ms: Date.now(),
+    }));
+
+    const sentBodies: string[] = [];
+    const recorder = new SessionRecorder(
+      {
+        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" },
+            },
+          ));
+        },
+      },
+      {},
+    );
+
+    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);
+
+      // 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
+      (recorder as any)._tick();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(sentBodies).toHaveLength(1);
+    } finally {
+      recorder.stop();
+      warnSpy.mockRestore();
+      localStorage.removeItem(storageKey);
+      vi.useRealTimers();
+    }
+  });
+});

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

@@ -11,7 +11,7 @@ export type AnalyticsReplayOptions = {
   /**
    * Whether session replays are enabled.
    *
-   * @default false
+   * @default true
    */
   enabled?: boolean,
   /**
@@ -44,12 +44,19 @@ export type AnalyticsOptions = {
    */
   enabled?: boolean,
   /**
-   * Options for session replay recording. Replays are disabled by default;
-   * set `enabled: true` to opt in.
+   * Options for session replay recording. Replays are enabled by default;
+   * set `enabled: false` to opt out.
    */
   replays?: AnalyticsReplayOptions,
 };
 
+export function getSessionReplayOptions(analyticsOptions: AnalyticsOptions | undefined): AnalyticsReplayOptions {
+  return {
+    ...analyticsOptions?.replays,
+    enabled: analyticsOptions?.replays?.enabled ?? true,
+  };
+}
+
 /**
  * Converts AnalyticsOptions to a JSON-safe representation.
  * RegExp blockClass values are serialized as `{ __regexp, __flags }` objects.
@@ -161,6 +168,7 @@ export type SessionRecorderDeps = {
 export class SessionRecorder {
   private _started = false;
   private _cancelled = false;
+  private _disabled = false;
   private _stopRecording: (() => void) | null = null;
   private _detachListeners: (() => void) | null = null;
   private _flushTimer: ReturnType<typeof setInterval> | null = null;
@@ -228,6 +236,7 @@ export class SessionRecorder {
   }
 
   private async _flush(options: { keepalive: boolean }) {
+    if (this._disabled) return;
     if (this._events.length === 0) return;
     // Prevent concurrent in-flight HTTP requests. When a flush is already
     // in-flight, a second batch could race on the server (both call
@@ -265,6 +274,18 @@ export class SessionRecorder {
       }
 
       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 {

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

@@ -40,8 +40,8 @@ export type StackClientAppConstructorOptions<HasTokenStore extends boolean, Proj
   noAutomaticPrefetch?: boolean,
 
   /**
-   * Options for analytics and session recording. Replays are disabled by default;
-   * set `{ replays: { enabled: true } }` to opt in.
+   * Options for analytics and session recording. Replays are enabled by default;
+   * set `{ replays: { enabled: false } }` to opt out.
    */
   analytics?: AnalyticsOptions,
 } & (
@@ -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

@@ -176,17 +176,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',