@hexclave/js 1.0.25 → 1.0.27

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

@@ -4,7 +4,7 @@
 //===========================================
 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 { captureWarning, throwErr } from "@hexclave/shared/dist/utils/errors";
 import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
 import { Result } from "@hexclave/shared/dist/utils/results";
 
@@ -110,6 +110,9 @@ const IDLE_TTL_MS = 3 * 60 * 1000;
 const FLUSH_INTERVAL_MS = 5_000;
 const MAX_EVENTS_PER_BATCH = 200;
 const MAX_APPROX_BYTES_PER_BATCH = 512_000;
+// The server rejects payloads > 1MB. Stay well under to account for JSON
+// envelope overhead (browser_session_id, timestamps, wrapper keys, etc.).
+const MAX_FLUSH_PAYLOAD_BYTES = 900_000;
 
 export type StoredSession = {
   session_id: string,
@@ -193,6 +196,7 @@ export class SessionRecorder {
   private _detachListeners: (() => void) | null = null;
   private _flushTimer: ReturnType<typeof setInterval> | null = null;
   private _events: unknown[] = [];
+  private _eventSizes: number[] = [];
   private _approxBytes = 0;
   private _lastPersistActivity = 0;
   private _recording = false;
@@ -243,6 +247,7 @@ export class SessionRecorder {
 
   clearBuffer() {
     this._events = [];
+    this._eventSizes = [];
     this._approxBytes = 0;
   }
 
@@ -268,42 +273,68 @@ export class SessionRecorder {
     const nowMs = Date.now();
     const stored = getOrRotateSession({ key: this._storageKey, legacyKey: this._legacyStorageKey, nowMs });
 
-    const batchId = generateUuid();
-    const payload = {
-      browser_session_id: stored.session_id,
-      session_replay_segment_id: this._sessionReplaySegmentId,
-      batch_id: batchId,
-      started_at_ms: stored.created_at_ms,
-      sent_at_ms: nowMs,
-      events: this._events,
-    };
-
+    // Capture all buffered events upfront (before any await) so that
+    // stop() / _stopCurrentRecording() clearing this._events cannot race
+    // with the async send loop below and silently discard overflow batches.
+    const allEvents = this._events;
+    const allSizes = this._eventSizes;
     this._events = [];
+    this._eventSizes = [];
     this._approxBytes = 0;
 
     this._flushInProgress = true;
     try {
-      const res = await this._deps.sendBatch(
-        JSON.stringify(payload),
-        { keepalive: options.keepalive },
-      );
-
-      if (res.status === "error") {
-        if (isAnalyticsNotEnabledError(res.error)) {
-          this._disable();
-          return;
+      let offset = 0;
+      while (offset < allEvents.length) {
+        // Build a batch that fits under the server's payload limit.
+        // When _flushInProgress blocked earlier flushes, events can accumulate
+        // well past MAX_APPROX_BYTES_PER_BATCH; sending them all at once would
+        // exceed the server's 1MB body limit (413).
+        let batchBytes = 0;
+        let batchEnd = offset;
+        for (let i = offset; i < allEvents.length; i++) {
+          const nextSize = allSizes[i] ?? throwErr("_eventSizes out of sync with _events — this should never happen");
+          if (batchBytes + nextSize > MAX_FLUSH_PAYLOAD_BYTES && batchEnd > offset) break;
+          batchBytes += nextSize;
+          batchEnd = i + 1;
         }
-        // Ad blockers commonly block analytics endpoints, causing network
-        // errors. These are expected and should not pollute the console.
-        if (isAdBlockerNetworkError(res.error)) {
+
+        const batchEvents = allEvents.slice(offset, batchEnd);
+        offset = batchEnd;
+
+        const batchId = generateUuid();
+        const payload = {
+          browser_session_id: stored.session_id,
+          session_replay_segment_id: this._sessionReplaySegmentId,
+          batch_id: batchId,
+          started_at_ms: stored.created_at_ms,
+          sent_at_ms: nowMs,
+          events: batchEvents,
+        };
+
+        const res = await this._deps.sendBatch(
+          JSON.stringify(payload),
+          { keepalive: options.keepalive },
+        );
+
+        if (res.status === "error") {
+          if (isAnalyticsNotEnabledError(res.error)) {
+            this._disable();
+            return;
+          }
+          // Ad blockers commonly block analytics endpoints, causing network
+          // errors. These are expected and should not pollute the console.
+          if (isAdBlockerNetworkError(res.error)) {
+            return;
+          }
+          captureWarning("SessionRecorder.flush", res.error);
           return;
         }
-        captureWarning("SessionRecorder.flush", res.error);
-        return;
-      }
 
-      if (!res.data.ok) {
-        captureWarning("SessionRecorder.flush", new Error(`SessionRecorder flush failed: ${res.data.status} ${await res.data.text()}`));
+        if (!res.data.ok) {
+          captureWarning("SessionRecorder.flush", new Error(`SessionRecorder flush failed: ${res.data.status} ${await res.data.text()}`));
+          return;
+        }
       }
     } finally {
       this._flushInProgress = false;
@@ -357,8 +388,10 @@ export class SessionRecorder {
           }
         }
 
+        const eventSize = JSON.stringify(event).length;
         this._events.push(event);
-        this._approxBytes += JSON.stringify(event).length;
+        this._eventSizes.push(eventSize);
+        this._approxBytes += eventSize;
         if (this._events.length >= MAX_EVENTS_PER_BATCH || this._approxBytes >= MAX_APPROX_BYTES_PER_BATCH) {
           runAsynchronously(() => this._flush({ keepalive: false }));
         }
@@ -391,6 +424,7 @@ export class SessionRecorder {
       this._stopRecording = null;
     }
     this._events = [];
+    this._eventSizes = [];
     this._approxBytes = 0;
     this._recording = false;
   }

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

@@ -13,6 +13,7 @@ import { AsyncStoreProperty, EmailConfig } from "../../common";
 import { AdminEmailOutbox, AdminSentEmail } from "../../email";
 import { InternalApiKey, InternalApiKeyCreateOptions, InternalApiKeyFirstView } from "../../internal-api-keys";
 import { AdminProjectPermission, AdminProjectPermissionDefinition, AdminProjectPermissionDefinitionCreateOptions, AdminProjectPermissionDefinitionUpdateOptions, AdminTeamPermission, AdminTeamPermissionDefinition, AdminTeamPermissionDefinitionCreateOptions, AdminTeamPermissionDefinitionUpdateOptions } from "../../permissions";
+import type { PlanUsage } from "../../plan-usage";
 import { AdminProject } from "../../projects";
 import { _HexclaveAdminAppImpl } from "../implementations";
 import { StackServerApp, StackServerAppConstructorOptions } from "./server-app";
@@ -75,6 +76,7 @@ export type StackAdminAppConstructorOptions<HasTokenStore extends boolean, Proje
 /** @deprecated Use `HexclaveAdminApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */
 export type StackAdminApp<HasTokenStore extends boolean = boolean, ProjectId extends string = string> = (
   & AsyncStoreProperty<"project", [], AdminProject, false>
+  & AsyncStoreProperty<"planUsage", [], PlanUsage, false>
   & AsyncStoreProperty<"internalApiKeys", [], InternalApiKey[], true>
   & AsyncStoreProperty<"teamPermissionDefinitions", [], AdminTeamPermissionDefinition[], true>
   & AsyncStoreProperty<"projectPermissionDefinitions", [], AdminProjectPermissionDefinition[], true>

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

@@ -123,6 +123,7 @@ export type StackClientApp<HasTokenStore extends boolean = boolean, ProjectId ex
       sendAnalyticsEventBatch(body: string, options: { keepalive: boolean }): Promise<Result<Response, Error>>,
       addRequestListener(listener: RequestListener): () => void,
       sendRequest(path: string, requestOptions: RequestInit, requestType?: "client" | "server" | "admin"): Promise<Response>,
+      getUrls(): Readonly<ResolvedHandlerUrls>,
       getRedirectMethod(): RedirectMethod,
       redirectToUrl(url: string | URL, options?: { replace?: boolean }): Promise<void>,
       redirectToHandler(handlerName: keyof HandlerUrls, options?: RedirectToOptions): Promise<void>,

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

@@ -118,6 +118,14 @@ export type {
   PushedConfigSource
 } from "./projects";
 
+export type {
+  PlanUsage,
+  PlanUsageKind,
+  PlanUsageNextPlanId,
+  PlanUsagePlanId,
+  PlanUsageRow,
+} from "./plan-usage";
+
 export type {
   EditableTeamMemberProfile, ReceivedTeamInvitation,
   SentTeamInvitation, ServerListUsersOptions,

package/src/lib/hexclave-app/plan-usage/index.ts

@@ -0,0 +1,29 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+export type PlanUsageKind = "current" | "metered" | "capability";
+export type PlanUsagePlanId = "free" | "team" | "growth";
+export type PlanUsageNextPlanId = "team" | "growth";
+
+export type PlanUsageRow = {
+  itemId: string,
+  displayName: string,
+  kind: PlanUsageKind,
+  used: number | null,
+  limit: number | null,
+  remaining: number | null,
+  overage: number | null,
+  isUnlimited: boolean,
+};
+
+export type PlanUsage = {
+  ownerTeamId: string,
+  ownerTeamDisplayName: string,
+  planId: PlanUsagePlanId,
+  planDisplayName: string,
+  periodStart: Date,
+  periodEnd: Date,
+  nextPlanId: PlanUsageNextPlanId | null,
+  rows: PlanUsageRow[],
+};

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

@@ -44,6 +44,7 @@ export type AdminProject = {
   readonly isDevelopmentEnvironment: boolean,
   readonly ownerTeamId: string | null,
   readonly onboardingStatus: ProjectOnboardingStatus,
+  readonly onboardingState: NonNullable<ProjectsCrud["Admin"]["Read"]["onboarding_state"]> | null,
   readonly logoUrl: string | null | undefined,
   readonly logoFullUrl: string | null | undefined,
   readonly logoDarkModeUrl: string | null | undefined,