@hexclave/shared 1.0.9 → 1.0.11

package/dist/sessions.test.js

@@ -0,0 +1,178 @@
+const require_chunk = require('./chunk-BE-pF4vm.js');
+let vitest = require("vitest");
+let __sessions_js = require("./sessions.js");
+
+//#region src/sessions.test.ts
+/**
+* Builds a decodable (unsigned) access-token JWT with a valid payload. `refreshTokenId` controls the
+* `refresh_token_id` claim (the session identifier); `iatOffsetSeconds` lets two tokens for the same session
+* differ as strings while sharing a `refresh_token_id`.
+*/
+function createAccessTokenString(refreshTokenId, options) {
+	const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+	const nowSeconds = Math.floor(Date.now() / 1e3) + (options?.iatOffsetSeconds ?? 0);
+	return [
+		encode({
+			alg: "none",
+			typ: "JWT"
+		}),
+		encode({
+			sub: options?.sub ?? "user-id",
+			exp: nowSeconds + 60,
+			iat: nowSeconds,
+			iss: "https://api.example.test",
+			aud: "project-id",
+			project_id: "project-id",
+			branch_id: "main",
+			refresh_token_id: refreshTokenId,
+			role: "authenticated",
+			name: null,
+			email: null,
+			email_verified: false,
+			selected_team_id: null,
+			signed_up_at: nowSeconds,
+			is_anonymous: false,
+			is_restricted: false,
+			restricted_reason: null,
+			requires_totp_mfa: false
+		}),
+		""
+	].join(".");
+}
+function createAccessOnlySession(accessToken) {
+	return new __sessions_js.InternalSession({
+		refreshAccessTokenCallback: async () => null,
+		refreshToken: null,
+		accessToken
+	});
+}
+const currentToken = (session) => session.getAccessTokenIfNotExpiredYet(2e4, null)?.token;
+(0, vitest.describe)("InternalSession.calculateSessionKey", () => {
+	(0, vitest.it)("keys by the refresh token when one is present (ignoring any access token)", () => {
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({ refreshToken: "rt-abc" })).toBe("refresh-rt-abc");
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: "rt-abc",
+			accessToken: createAccessTokenString("rtid-1")
+		})).toBe("refresh-rt-abc");
+	});
+	(0, vitest.it)("returns not-logged-in when neither token is present", () => {
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({ refreshToken: null })).toBe("not-logged-in");
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: null
+		})).toBe("not-logged-in");
+	});
+	(0, vitest.it)("keys an access-only session by its refresh_token_id", () => {
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: createAccessTokenString("rtid-1")
+		})).toBe("access-session-rtid-1");
+	});
+	(0, vitest.it)("is stable across re-minted access tokens for the same session (the regression this fixes)", () => {
+		const first = createAccessTokenString("rtid-1", { iatOffsetSeconds: 0 });
+		const second = createAccessTokenString("rtid-1", { iatOffsetSeconds: 1 });
+		(0, vitest.expect)(second).not.toBe(first);
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: second
+		})).toBe(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: first
+		}));
+	});
+	(0, vitest.it)("distinguishes access-only sessions with different refresh_token_ids", () => {
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: createAccessTokenString("rtid-1")
+		})).not.toBe(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: createAccessTokenString("rtid-2")
+		}));
+	});
+	(0, vitest.it)("falls back to the raw token when the access token can't be decoded", () => {
+		(0, vitest.expect)(__sessions_js.InternalSession.calculateSessionKey({
+			refreshToken: null,
+			accessToken: "not-a-jwt"
+		})).toBe("access-not-a-jwt");
+	});
+});
+(0, vitest.describe)("InternalSession#updateAccessToken", () => {
+	(0, vitest.it)("installs a fresh token for the same access-only session in place", () => {
+		const initial = createAccessTokenString("rtid-1", { iatOffsetSeconds: 0 });
+		const refreshed = createAccessTokenString("rtid-1", { iatOffsetSeconds: 1 });
+		const session = createAccessOnlySession(initial);
+		session.updateAccessToken({
+			accessToken: refreshed,
+			refreshToken: null
+		});
+		(0, vitest.expect)(currentToken(session)).toBe(refreshed);
+		(0, vitest.expect)(session.sessionKey).toBe("access-session-rtid-1");
+	});
+	(0, vitest.it)("rejects a token pair belonging to a different access-only session", () => {
+		const initial = createAccessTokenString("rtid-1");
+		const foreign = createAccessTokenString("rtid-2", { sub: "other-user" });
+		const session = createAccessOnlySession(initial);
+		session.updateAccessToken({
+			accessToken: foreign,
+			refreshToken: null
+		});
+		(0, vitest.expect)(currentToken(session)).toBe(initial);
+	});
+	(0, vitest.it)("is a no-op for an unchanged, null, or undecodable token", () => {
+		const initial = createAccessTokenString("rtid-1");
+		const session = createAccessOnlySession(initial);
+		session.updateAccessToken({
+			accessToken: initial,
+			refreshToken: null
+		});
+		session.updateAccessToken({
+			accessToken: null,
+			refreshToken: null
+		});
+		session.updateAccessToken({
+			accessToken: "not-a-jwt",
+			refreshToken: null
+		});
+		(0, vitest.expect)(currentToken(session)).toBe(initial);
+	});
+	(0, vitest.it)("never revives an invalidated session", () => {
+		const session = createAccessOnlySession(createAccessTokenString("rtid-1"));
+		session.markInvalid();
+		session.updateAccessToken({
+			accessToken: createAccessTokenString("rtid-1", { iatOffsetSeconds: 1 }),
+			refreshToken: null
+		});
+		(0, vitest.expect)(session.isKnownToBeInvalid()).toBe(true);
+		(0, vitest.expect)(currentToken(session)).toBeUndefined();
+	});
+	(0, vitest.it)("updates a refresh-token-backed session's access token in place when the refresh token matches", () => {
+		const session = new __sessions_js.InternalSession({
+			refreshAccessTokenCallback: async () => null,
+			refreshToken: "rt-abc",
+			accessToken: createAccessTokenString("rtid-1")
+		});
+		const refreshed = createAccessTokenString("rtid-2", { iatOffsetSeconds: 1 });
+		session.updateAccessToken({
+			accessToken: refreshed,
+			refreshToken: "rt-abc"
+		});
+		(0, vitest.expect)(currentToken(session)).toBe(refreshed);
+		(0, vitest.expect)(session.sessionKey).toBe("refresh-rt-abc");
+	});
+	(0, vitest.it)("rejects a token pair carrying a different refresh token for a refresh-backed session", () => {
+		const initial = createAccessTokenString("rtid-1");
+		const session = new __sessions_js.InternalSession({
+			refreshAccessTokenCallback: async () => null,
+			refreshToken: "rt-abc",
+			accessToken: initial
+		});
+		session.updateAccessToken({
+			accessToken: createAccessTokenString("rtid-2"),
+			refreshToken: "rt-other"
+		});
+		(0, vitest.expect)(currentToken(session)).toBe(initial);
+	});
+});
+
+//#endregion
+//# sourceMappingURL=sessions.test.js.map

package/dist/sessions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.test.js","names":["InternalSession"],"sources":["../src/sessions.test.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport { InternalSession } from \"./sessions\";\n\n/**\n * Builds a decodable (unsigned) access-token JWT with a valid payload. `refreshTokenId` controls the\n * `refresh_token_id` claim (the session identifier); `iatOffsetSeconds` lets two tokens for the same session\n * differ as strings while sharing a `refresh_token_id`.\n */\nfunction createAccessTokenString(refreshTokenId: string, options?: { iatOffsetSeconds?: number, sub?: string }): string {\n  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString(\"base64url\");\n  const nowSeconds = Math.floor(Date.now() / 1000) + (options?.iatOffsetSeconds ?? 0);\n  return [\n    encode({ alg: \"none\", typ: \"JWT\" }),\n    encode({\n      sub: options?.sub ?? \"user-id\",\n      exp: nowSeconds + 60,\n      iat: nowSeconds,\n      iss: \"https://api.example.test\",\n      aud: \"project-id\",\n      project_id: \"project-id\",\n      branch_id: \"main\",\n      refresh_token_id: refreshTokenId,\n      role: \"authenticated\",\n      name: null,\n      email: null,\n      email_verified: false,\n      selected_team_id: null,\n      signed_up_at: nowSeconds,\n      is_anonymous: false,\n      is_restricted: false,\n      restricted_reason: null,\n      requires_totp_mfa: false,\n    }),\n    \"\",\n  ].join(\".\");\n}\n\nfunction createAccessOnlySession(accessToken: string): InternalSession {\n  return new InternalSession({\n    refreshAccessTokenCallback: async () => null,\n    refreshToken: null,\n    accessToken,\n  });\n}\n\nconst currentToken = (session: InternalSession) => session.getAccessTokenIfNotExpiredYet(20_000, null)?.token;\n\ndescribe(\"InternalSession.calculateSessionKey\", () => {\n  it(\"keys by the refresh token when one is present (ignoring any access token)\", () => {\n    expect(InternalSession.calculateSessionKey({ refreshToken: \"rt-abc\" })).toBe(\"refresh-rt-abc\");\n    expect(InternalSession.calculateSessionKey({ refreshToken: \"rt-abc\", accessToken: createAccessTokenString(\"rtid-1\") }))\n      .toBe(\"refresh-rt-abc\");\n  });\n\n  it(\"returns not-logged-in when neither token is present\", () => {\n    expect(InternalSession.calculateSessionKey({ refreshToken: null })).toBe(\"not-logged-in\");\n    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: null })).toBe(\"not-logged-in\");\n  });\n\n  it(\"keys an access-only session by its refresh_token_id\", () => {\n    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: createAccessTokenString(\"rtid-1\") }))\n      .toBe(\"access-session-rtid-1\");\n  });\n\n  it(\"is stable across re-minted access tokens for the same session (the regression this fixes)\", () => {\n    const first = createAccessTokenString(\"rtid-1\", { iatOffsetSeconds: 0 });\n    const second = createAccessTokenString(\"rtid-1\", { iatOffsetSeconds: 1 });\n    expect(second).not.toBe(first);\n    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: second }))\n      .toBe(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: first }));\n  });\n\n  it(\"distinguishes access-only sessions with different refresh_token_ids\", () => {\n    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: createAccessTokenString(\"rtid-1\") }))\n      .not.toBe(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: createAccessTokenString(\"rtid-2\") }));\n  });\n\n  it(\"falls back to the raw token when the access token can't be decoded\", () => {\n    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: \"not-a-jwt\" })).toBe(\"access-not-a-jwt\");\n  });\n});\n\ndescribe(\"InternalSession#updateAccessToken\", () => {\n  it(\"installs a fresh token for the same access-only session in place\", () => {\n    const initial = createAccessTokenString(\"rtid-1\", { iatOffsetSeconds: 0 });\n    const refreshed = createAccessTokenString(\"rtid-1\", { iatOffsetSeconds: 1 });\n    const session = createAccessOnlySession(initial);\n\n    session.updateAccessToken({ accessToken: refreshed, refreshToken: null });\n    expect(currentToken(session)).toBe(refreshed);\n    // identity is unchanged — same session key, same object\n    expect(session.sessionKey).toBe(\"access-session-rtid-1\");\n  });\n\n  it(\"rejects a token pair belonging to a different access-only session\", () => {\n    const initial = createAccessTokenString(\"rtid-1\");\n    const foreign = createAccessTokenString(\"rtid-2\", { sub: \"other-user\" });\n    const session = createAccessOnlySession(initial);\n\n    session.updateAccessToken({ accessToken: foreign, refreshToken: null });\n    expect(currentToken(session)).toBe(initial);\n  });\n\n  it(\"is a no-op for an unchanged, null, or undecodable token\", () => {\n    const initial = createAccessTokenString(\"rtid-1\");\n    const session = createAccessOnlySession(initial);\n\n    session.updateAccessToken({ accessToken: initial, refreshToken: null });\n    session.updateAccessToken({ accessToken: null, refreshToken: null });\n    session.updateAccessToken({ accessToken: \"not-a-jwt\", refreshToken: null });\n    expect(currentToken(session)).toBe(initial);\n  });\n\n  it(\"never revives an invalidated session\", () => {\n    const session = createAccessOnlySession(createAccessTokenString(\"rtid-1\"));\n    session.markInvalid();\n\n    session.updateAccessToken({ accessToken: createAccessTokenString(\"rtid-1\", { iatOffsetSeconds: 1 }), refreshToken: null });\n    expect(session.isKnownToBeInvalid()).toBe(true);\n    expect(currentToken(session)).toBeUndefined();\n  });\n\n  it(\"updates a refresh-token-backed session's access token in place when the refresh token matches\", () => {\n    const session = new InternalSession({\n      refreshAccessTokenCallback: async () => null,\n      refreshToken: \"rt-abc\",\n      accessToken: createAccessTokenString(\"rtid-1\"),\n    });\n    const refreshed = createAccessTokenString(\"rtid-2\", { iatOffsetSeconds: 1 });\n\n    session.updateAccessToken({ accessToken: refreshed, refreshToken: \"rt-abc\" });\n    expect(currentToken(session)).toBe(refreshed);\n    expect(session.sessionKey).toBe(\"refresh-rt-abc\");\n  });\n\n  it(\"rejects a token pair carrying a different refresh token for a refresh-backed session\", () => {\n    const initial = createAccessTokenString(\"rtid-1\");\n    const session = new InternalSession({\n      refreshAccessTokenCallback: async () => null,\n      refreshToken: \"rt-abc\",\n      accessToken: initial,\n    });\n\n    session.updateAccessToken({ accessToken: createAccessTokenString(\"rtid-2\"), refreshToken: \"rt-other\" });\n    expect(currentToken(session)).toBe(initial);\n  });\n});\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexclave/shared",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "repository": "https://github.com/hexclave/hexclave",
   "files": [
     "README.md",

package/src/ai/unified-prompts/reminders.ts

@@ -18,6 +18,7 @@ export const remindersPrompt = deindent`
   - Language, framework, and library-specific details:
     - JavaScript & TypeScript:
       - Hexclave has different SDK packages for different frameworks and languages. As of the time of writing these reminders, they are: @hexclave/js (JavaScript/TypeScript), @hexclave/next (Next.js), @hexclave/react (React), @hexclave/tanstack-start (TanStack Start). You can find all of these on npm. They are all versioned together, meaning that vX.Y.Z of one SDK was released at the same time as vX.Y.Z of another SDK. For the most part, they are the same, although each has platform-specific features and differences.
+      - The Hexclave/Stack Auth SDK constructor accepts a \`urls\` option that tells the SDK where auth pages and post-auth redirects live. When you add a custom auth page such as a \`sign-in\`, \`sign-up\`, \`forgot-password\`, \`account-settings\`, etc., update the corresponding \`urls\` key to point to that route; also set redirect targets such as \`afterSignIn\`, \`afterSignUp\`, \`afterSignOut\`, and \`home\` when those destinations are customized. The \`urls\` option is the source of truth for redirect helpers such as \`redirectToSignIn()\`, hosted or handler-page flows, and post-auth navigation; if it is left pointing at the default pages after custom pages are added, users can hit extra redirects, land on the wrong auth page, or return to an unexpected page after signing in or out.
       - The \`Result<T, E>\` type is \`{ status: "ok", data: T } | { status: "error", error: E }\`.
       - \`KnownErrors[KNOWN_ERROR_CODE]\` refers to a specific known error type. Each KnownError may have its own properties, but they all inherit from \`Error & { statusCode: number, humanReadableMessage: string, details?: Json }\`.
       - React & Next.js:

package/src/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.ts

@@ -442,11 +442,13 @@ function getRestBackendSetupPrompt(kind: "python" | "rest-api") {
             If this project already has a \`hexclave.config.ts\` file for another frontend or backend, reuse that same file so the whole project shares one Hexclave config. Otherwise, create a new \`hexclave.config.ts\` file in your workspace:
 
             \`\`\`ts hexclave.config.ts
-            import type { HexclaveConfig } from "@hexclave/js";
+            import type { HexclaveConfig } from "@hexclave/js/config";
 
             export const config: HexclaveConfig = "show-onboarding";
             \`\`\`
 
+            The \`/config\` entrypoint is lightweight and free of framework runtime code, so it can be safely loaded by tooling such as the local dashboard. If you later switch to a config object and want type-checking, wrap it with \`defineHexclaveConfig\` imported from the same \`@hexclave/js/config\` path (never from \`@hexclave/js\` directly, which would pull in the whole SDK and fail to load).
+
             Run your backend through the Hexclave CLI so it starts the local dashboard and injects the Hexclave environment variables:
 
             \`\`\`json package.json
@@ -662,6 +664,10 @@ export function getSdkSetupPrompt(mainType: "ai-prompt" | "nextjs" | "react" | "
             },
           });
           \`\`\`
+
+          <Note>
+            The SDK auto-captures page-view and click analytics. To turn this off (and silence the \`ANALYTICS_NOT_ENABLED\` console warning that appears until you enable the Analytics app in your dashboard), pass \`analytics: { enabled: false }\`.
+          </Note>
         ` : ""}
 
         ${isMaybeBackend ? deindent`
@@ -719,12 +725,14 @@ export function getSdkSetupPrompt(mainType: "ai-prompt" | "nextjs" | "react" | "
             First, create a \`hexclave.config.ts\` configuration file in the root directory of the workspace (or anywhere else):
 
             \`\`\`ts hexclave.config.ts
-            import type { HexclaveConfig } from "${packageName}";
+            import type { HexclaveConfig } from "${packageName}/config";
 
             // default: show-onboarding, which shows the onboarding flow for this project when Hexclave starts
             export const config: HexclaveConfig = "show-onboarding";
             \`\`\`
 
+            The \`/config\` entrypoint is lightweight and free of framework runtime code, so it can be safely loaded by tooling such as the local dashboard. If you later switch to a config object and want type-checking, wrap it with \`defineHexclaveConfig\` imported from the same \`${packageName}/config\` path (never from \`${packageName}\` directly, which would pull in the whole SDK and fail to load).
+
             To run your application with Hexclave, you can then start the dev environment and set environment variables expected by your application. Hexclave's CLI has a \`dev\` command does both of these, so let's install it as a dev dependency and wrap your existing \`dev\` script in your package.json:
 
             \`\`\`sh

package/src/config-rendering.ts

@@ -13,6 +13,7 @@ export { parseHexclaveConfigFileContent, renderConfigFileContent };
 const CONFIG_IMPORT_PACKAGES = [
   "@hexclave/next",
   "@hexclave/react",
+  "@hexclave/tanstack-start",
   "@hexclave/js",
   "@hexclave/template",
   "@stackframe/stack",
@@ -120,18 +121,26 @@ import.meta.vitest?.test("renderConfigFileContent rejects invalid config exports
 
 import.meta.vitest?.test("renderConfigFileContent uses custom import package", ({ expect }) => {
   const content = renderConfigFileContent({}, "@hexclave/next");
-  expect(content).toContain('import type { HexclaveConfig } from "@hexclave/next";');
+  expect(content).toContain('import type { HexclaveConfig } from "@hexclave/next/config";');
 });
 
 import.meta.vitest?.test("renderConfigFileContent defaults to @hexclave/js", ({ expect }) => {
   const content = renderConfigFileContent({});
-  expect(content).toContain('import type { HexclaveConfig } from "@hexclave/js";');
+  expect(content).toContain('import type { HexclaveConfig } from "@hexclave/js/config";');
+});
+
+import.meta.vitest?.test("renderConfigFileContent keeps legacy @stackframe packages on their root entrypoint", ({ expect }) => {
+  // The lightweight `/config` subpath only exists on Hexclave-branded packages;
+  // already-published @stackframe/* releases predate it.
+  const content = renderConfigFileContent({}, "@stackframe/next");
+  expect(content).toContain('import type { HexclaveConfig } from "@stackframe/next";');
 });
 
 import.meta.vitest?.test("detectConfigImportPackage picks first matching package by priority", ({ expect }) => {
   expect(detectConfigImportPackage(["@hexclave/next", "@hexclave/js"])).toBe("@hexclave/next");
   expect(detectConfigImportPackage(["@hexclave/react", "@hexclave/js"])).toBe("@hexclave/react");
   expect(detectConfigImportPackage(["@hexclave/js"])).toBe("@hexclave/js");
+  expect(detectConfigImportPackage(["@hexclave/tanstack-start"])).toBe("@hexclave/tanstack-start");
   // Hexclave names take priority over legacy stackframe names when both appear.
   expect(detectConfigImportPackage(["@stackframe/stack", "@hexclave/next"])).toBe("@hexclave/next");
   // Legacy fallback still works for projects pinned to the last @stackframe/* release.

package/src/hexclave-config-file.ts

@@ -28,7 +28,13 @@ export function renderConfigFileContent(config: unknown, importPackage?: string)
     throw new Error(`Config has conflicting keys that would be dropped during normalization: ${droppedKeys.map(k => JSON.stringify(k)).join(", ")}`);
   }
   const pkg = importPackage ?? DEFAULT_CONFIG_IMPORT_PACKAGE;
-  const importLine = `import type { HexclaveConfig } from "${pkg}";`;
+  // Import the `HexclaveConfig` type from the package's lightweight `/config`
+  // entrypoint, which is free of framework runtime code and therefore safe for
+  // tooling (e.g. the local dashboard) to load in a plain Node context. Only the
+  // Hexclave-branded packages expose this subpath; legacy `@stackframe/*`
+  // releases predate it, so fall back to their package root.
+  const importSpecifier = pkg.startsWith("@hexclave/") ? `${pkg}/config` : pkg;
+  const importLine = `import type { HexclaveConfig } from "${importSpecifier}";`;
   return `${importLine}\n\nexport const config: HexclaveConfig = ${JSON.stringify(normalizedConfig, null, 2)};\n`;
 }
 

package/src/interface/admin-interface.ts

@@ -361,11 +361,29 @@ export class HexclaveAdminInterface extends HexclaveServerInterface {
     );
   }
 
-  async getMetrics(includeAnonymous: boolean = false): Promise<MetricsResponse> {
+  async getMetrics(
+    includeAnonymous: boolean = false,
+    filters?: {
+      country_code?: string,
+      referrer?: string,
+      browser?: string,
+      os?: string,
+      device?: string,
+      since?: string,
+      until?: string,
+    },
+  ): Promise<MetricsResponse> {
     const params = new URLSearchParams();
     if (includeAnonymous) {
       params.append('include_anonymous', 'true');
     }
+    if (filters?.country_code) params.append('filter_country_code', filters.country_code);
+    if (filters?.referrer) params.append('filter_referrer', filters.referrer);
+    if (filters?.browser) params.append('filter_browser', filters.browser);
+    if (filters?.os) params.append('filter_os', filters.os);
+    if (filters?.device) params.append('filter_device', filters.device);
+    if (filters?.since) params.append('filter_since', filters.since);
+    if (filters?.until) params.append('filter_until', filters.until);
     const queryString = params.toString();
     const response = await this.sendAdminRequest(
       `/internal/metrics${queryString ? `?${queryString}` : ''}`,
@@ -374,7 +392,36 @@ export class HexclaveAdminInterface extends HexclaveServerInterface {
       },
       null,
     );
-    return (await response.json()) as MetricsResponse;
+    const body = (await response.json()) as MetricsResponse;
+    // The yup schema's .optional().default(...) fallbacks only run during
+    // backend response validation, not on this client-side cast — apply them
+    // here too so the one-release-cycle tolerance for older servers that the
+    // schema comments promise actually holds for dashboard consumers. The
+    // Partial views widen the static type (which claims these are always
+    // defined) to match what an older server can actually send.
+    const rawBody: Partial<MetricsResponse> = body;
+    const rawAnalytics: Partial<MetricsResponse["analytics_overview"]> = body.analytics_overview;
+    return {
+      ...body,
+      live_users: rawBody.live_users ?? 0,
+      hourly_users: rawBody.hourly_users ?? [],
+      hourly_active_users: rawBody.hourly_active_users ?? [],
+      analytics_overview: {
+        ...body.analytics_overview,
+        hourly_page_views: rawAnalytics.hourly_page_views ?? [],
+        hourly_active_users: rawAnalytics.hourly_active_users ?? [],
+        hourly_visitors: rawAnalytics.hourly_visitors ?? [],
+        daily_anonymous_visitors_fallback: rawAnalytics.daily_anonymous_visitors_fallback ?? [],
+        anonymous_visitors_fallback: rawAnalytics.anonymous_visitors_fallback ?? 0,
+        top_regions: rawAnalytics.top_regions ?? [],
+        bounce_rate: rawAnalytics.bounce_rate ?? 0,
+        daily_bounce_rate: rawAnalytics.daily_bounce_rate ?? [],
+        daily_avg_session_seconds: rawAnalytics.daily_avg_session_seconds ?? [],
+        top_browsers: rawAnalytics.top_browsers ?? [],
+        top_operating_systems: rawAnalytics.top_operating_systems ?? [],
+        top_devices: rawAnalytics.top_devices ?? [],
+      },
+    };
   }
 
   async getUserActivity(userId: string): Promise<UserActivityResponse> {

package/src/interface/admin-metrics.ts

@@ -88,16 +88,31 @@ export const MetricsTopReferrerSchema = yupObject({
   visitors: yupNumber().integer().defined(),
 }).defined();
 
+// Named-count breakdowns used by the analytics overview for top browsers,
+// operating systems, and device classes (Desktop / Mobile / Tablet).
+export const MetricsNamedCountSchema = yupObject({
+  name: yupString().defined(),
+  visitors: yupNumber().integer().defined(),
+}).defined();
+
 export const MetricsTopRegionSchema = yupObject({
   country_code: yupString().nullable().defined(),
   region_code: yupString().nullable().defined(),
   count: yupNumber().integer().defined(),
 }).defined();
 
+export const MetricsTopCountrySchema = yupObject({
+  country_code: yupString().defined(),
+  count: yupNumber().integer().defined(),
+}).defined();
+
 export const MetricsAnalyticsOverviewSchema = yupObject({
   daily_page_views: MetricsDataPointsSchema,
   daily_clicks: MetricsDataPointsSchema,
   daily_visitors: MetricsDataPointsSchema,
+  hourly_page_views: yupArray(MetricsDataPointSchema).optional().default([]),
+  hourly_active_users: yupArray(MetricsDataPointSchema).optional().default([]),
+  hourly_visitors: yupArray(MetricsDataPointSchema).optional().default([]),
   // Token-refresh-derived anonymous-visitor fallback. Populated only when the
   // analytics app isn't installed (no `$page-view` events) — counts DISTINCT
   // anonymous users per day from the events table. See
@@ -117,8 +132,20 @@ export const MetricsAnalyticsOverviewSchema = yupObject({
   revenue_per_visitor: yupNumber().defined(),
   top_referrers: yupArray(MetricsTopReferrerSchema).defined(),
   top_region: MetricsTopRegionSchema.nullable().defined(),
-  // dev-fallback fields (only present in non-production environments)
-  bounce_rate: yupNumber().optional(),
+  top_regions: yupArray(MetricsTopCountrySchema).optional().default([]),
+  // Weighted across the window: sum(bounced)/sum(sessions) * 100. .optional()
+  // for one release cycle so older servers (that don't return it yet) don't
+  // hard-fail validation; default to 0 so consumers can read unconditionally.
+  bounce_rate: yupNumber().optional().default(0),
+  daily_bounce_rate: yupArray(MetricsDataPointSchema).optional().default([]),
+  daily_avg_session_seconds: yupArray(MetricsDataPointSchema).optional().default([]),
+  // User-Agent-derived breakdowns for the analytics overview. Computed from the
+  // `data.user_agent` blob on `$page-view` events (captured client-side only,
+  // no server-side fallback). Optional + default-[] for one release cycle
+  // so older clients / servers without UA capture don't fail validation.
+  top_browsers: yupArray(MetricsNamedCountSchema).optional().default([]),
+  top_operating_systems: yupArray(MetricsNamedCountSchema).optional().default([]),
+  top_devices: yupArray(MetricsNamedCountSchema).optional().default([]),
   conversion_rate: yupNumber().optional(),
   deltas: yupMixed().optional(),
 }).defined();
@@ -176,6 +203,8 @@ export const MetricsResponseBodySchema = yupObject({
   live_users: yupNumber().integer().optional().default(0),
   daily_users: MetricsDataPointsSchema,
   daily_active_users: MetricsDataPointsSchema,
+  hourly_users: yupArray(MetricsDataPointSchema).optional().default([]),
+  hourly_active_users: yupArray(MetricsDataPointSchema).optional().default([]),
   users_by_country: yupRecord(yupString().defined(), yupNumber().defined()).defined(),
   active_users_by_country: MetricsActiveUsersByCountrySchema,
   // recently_registered/active are CRUD User objects passed through from the
@@ -206,6 +235,8 @@ export type MetricsEmailOverview = yup.InferType<typeof MetricsEmailOverviewSche
 export type MetricsDailyRevenuePoint = yup.InferType<typeof MetricsDailyRevenuePointSchema>;
 export type MetricsTopReferrer = yup.InferType<typeof MetricsTopReferrerSchema>;
 export type MetricsTopRegion = yup.InferType<typeof MetricsTopRegionSchema>;
+export type MetricsTopCountry = yup.InferType<typeof MetricsTopCountrySchema>;
+export type MetricsNamedCount = yup.InferType<typeof MetricsNamedCountSchema>;
 export type MetricsAnalyticsOverview = yup.InferType<typeof MetricsAnalyticsOverviewSchema>;
 export type MetricsLoginMethodEntry = yup.InferType<typeof MetricsLoginMethodEntrySchema>;
 export type MetricsRecentUser = yup.InferType<typeof MetricsRecentUserSchema>;

package/src/schema-fields.ts

@@ -612,7 +612,10 @@ export const emailHostSchema = yupString().meta({ openapiField: { description: '
 export const emailPortSchema = yupNumber().min(0).max(65535).meta({ openapiField: { description: 'Email port. Needs to be specified when using type="standard"', exampleValue: 587 } });
 export const emailUsernameSchema = yupString().meta({ openapiField: { description: 'Email username. Needs to be specified when using type="standard"', exampleValue: 'smtp-email' } });
 export const emailSenderEmailSchema = emailSchema.meta({ openapiField: { description: 'Email sender email. Needs to be specified when using type="standard"', exampleValue: 'example@your-domain.com' } });
-export const emailPasswordSchema = passwordSchema.meta({ openapiField: { description: 'Email password. Needs to be specified when using type="standard"', exampleValue: 'your-email-password' } });
+// SMTP credentials are stored encrypted (not bcrypt-hashed like user passwords), so they don't
+// need the 70-char bcrypt limit from passwordSchema. Some providers (e.g. ZeptoMail) generate
+// passwords well over 100 chars.
+export const emailPasswordSchema = yupString().max(256).meta({ openapiField: { description: 'Email password. Needs to be specified when using type="standard"', exampleValue: 'your-email-password' } });
 // Project domain config
 export const handlerPathSchema = yupString().test('is-handler-path', 'Handler path must start with /', (value) => value?.startsWith('/')).meta({ openapiField: { description: 'Handler path. If you did not setup a custom handler path, it should be "/handler" by default. It needs to start with /', exampleValue: '/handler' } });
 // Project email theme config

package/src/sessions.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import { InternalSession } from "./sessions";
+
+/**
+ * Builds a decodable (unsigned) access-token JWT with a valid payload. `refreshTokenId` controls the
+ * `refresh_token_id` claim (the session identifier); `iatOffsetSeconds` lets two tokens for the same session
+ * differ as strings while sharing a `refresh_token_id`.
+ */
+function createAccessTokenString(refreshTokenId: string, options?: { iatOffsetSeconds?: number, sub?: string }): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
+  const nowSeconds = Math.floor(Date.now() / 1000) + (options?.iatOffsetSeconds ?? 0);
+  return [
+    encode({ alg: "none", typ: "JWT" }),
+    encode({
+      sub: options?.sub ?? "user-id",
+      exp: nowSeconds + 60,
+      iat: nowSeconds,
+      iss: "https://api.example.test",
+      aud: "project-id",
+      project_id: "project-id",
+      branch_id: "main",
+      refresh_token_id: refreshTokenId,
+      role: "authenticated",
+      name: null,
+      email: null,
+      email_verified: false,
+      selected_team_id: null,
+      signed_up_at: nowSeconds,
+      is_anonymous: false,
+      is_restricted: false,
+      restricted_reason: null,
+      requires_totp_mfa: false,
+    }),
+    "",
+  ].join(".");
+}
+
+function createAccessOnlySession(accessToken: string): InternalSession {
+  return new InternalSession({
+    refreshAccessTokenCallback: async () => null,
+    refreshToken: null,
+    accessToken,
+  });
+}
+
+const currentToken = (session: InternalSession) => session.getAccessTokenIfNotExpiredYet(20_000, null)?.token;
+
+describe("InternalSession.calculateSessionKey", () => {
+  it("keys by the refresh token when one is present (ignoring any access token)", () => {
+    expect(InternalSession.calculateSessionKey({ refreshToken: "rt-abc" })).toBe("refresh-rt-abc");
+    expect(InternalSession.calculateSessionKey({ refreshToken: "rt-abc", accessToken: createAccessTokenString("rtid-1") }))
+      .toBe("refresh-rt-abc");
+  });
+
+  it("returns not-logged-in when neither token is present", () => {
+    expect(InternalSession.calculateSessionKey({ refreshToken: null })).toBe("not-logged-in");
+    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: null })).toBe("not-logged-in");
+  });
+
+  it("keys an access-only session by its refresh_token_id", () => {
+    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: createAccessTokenString("rtid-1") }))
+      .toBe("access-session-rtid-1");
+  });
+
+  it("is stable across re-minted access tokens for the same session (the regression this fixes)", () => {
+    const first = createAccessTokenString("rtid-1", { iatOffsetSeconds: 0 });
+    const second = createAccessTokenString("rtid-1", { iatOffsetSeconds: 1 });
+    expect(second).not.toBe(first);
+    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: second }))
+      .toBe(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: first }));
+  });
+
+  it("distinguishes access-only sessions with different refresh_token_ids", () => {
+    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: createAccessTokenString("rtid-1") }))
+      .not.toBe(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: createAccessTokenString("rtid-2") }));
+  });
+
+  it("falls back to the raw token when the access token can't be decoded", () => {
+    expect(InternalSession.calculateSessionKey({ refreshToken: null, accessToken: "not-a-jwt" })).toBe("access-not-a-jwt");
+  });
+});
+
+describe("InternalSession#updateAccessToken", () => {
+  it("installs a fresh token for the same access-only session in place", () => {
+    const initial = createAccessTokenString("rtid-1", { iatOffsetSeconds: 0 });
+    const refreshed = createAccessTokenString("rtid-1", { iatOffsetSeconds: 1 });
+    const session = createAccessOnlySession(initial);
+
+    session.updateAccessToken({ accessToken: refreshed, refreshToken: null });
+    expect(currentToken(session)).toBe(refreshed);
+    // identity is unchanged — same session key, same object
+    expect(session.sessionKey).toBe("access-session-rtid-1");
+  });
+
+  it("rejects a token pair belonging to a different access-only session", () => {
+    const initial = createAccessTokenString("rtid-1");
+    const foreign = createAccessTokenString("rtid-2", { sub: "other-user" });
+    const session = createAccessOnlySession(initial);
+
+    session.updateAccessToken({ accessToken: foreign, refreshToken: null });
+    expect(currentToken(session)).toBe(initial);
+  });
+
+  it("is a no-op for an unchanged, null, or undecodable token", () => {
+    const initial = createAccessTokenString("rtid-1");
+    const session = createAccessOnlySession(initial);
+
+    session.updateAccessToken({ accessToken: initial, refreshToken: null });
+    session.updateAccessToken({ accessToken: null, refreshToken: null });
+    session.updateAccessToken({ accessToken: "not-a-jwt", refreshToken: null });
+    expect(currentToken(session)).toBe(initial);
+  });
+
+  it("never revives an invalidated session", () => {
+    const session = createAccessOnlySession(createAccessTokenString("rtid-1"));
+    session.markInvalid();
+
+    session.updateAccessToken({ accessToken: createAccessTokenString("rtid-1", { iatOffsetSeconds: 1 }), refreshToken: null });
+    expect(session.isKnownToBeInvalid()).toBe(true);
+    expect(currentToken(session)).toBeUndefined();
+  });
+
+  it("updates a refresh-token-backed session's access token in place when the refresh token matches", () => {
+    const session = new InternalSession({
+      refreshAccessTokenCallback: async () => null,
+      refreshToken: "rt-abc",
+      accessToken: createAccessTokenString("rtid-1"),
+    });
+    const refreshed = createAccessTokenString("rtid-2", { iatOffsetSeconds: 1 });
+
+    session.updateAccessToken({ accessToken: refreshed, refreshToken: "rt-abc" });
+    expect(currentToken(session)).toBe(refreshed);
+    expect(session.sessionKey).toBe("refresh-rt-abc");
+  });
+
+  it("rejects a token pair carrying a different refresh token for a refresh-backed session", () => {
+    const initial = createAccessTokenString("rtid-1");
+    const session = new InternalSession({
+      refreshAccessTokenCallback: async () => null,
+      refreshToken: "rt-abc",
+      accessToken: initial,
+    });
+
+    session.updateAccessToken({ accessToken: createAccessTokenString("rtid-2"), refreshToken: "rt-other" });
+    expect(currentToken(session)).toBe(initial);
+  });
+});