@scalemule/nextjs 0.0.24 → 0.0.26

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { j as StorageAdapter } from './index-jomBa89d.mjs';
+import { j as StorageAdapter } from './index-CYS_FzSf.mjs';
 
 /**
  * ScaleMule API Client

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { j as StorageAdapter } from './index-jomBa89d.js';
+import { j as StorageAdapter } from './index-CYS_FzSf.js';
 
 /**
  * ScaleMule API Client

package/dist/{index-jomBa89d.d.mts → index-CYS_FzSf.d.mts}

@@ -614,6 +614,13 @@ interface UseAnalyticsOptions {
     anonymousStorageKey?: string;
     /** Use v2 enhanced tracking (default: true) */
     useV2?: boolean;
+    /**
+     * Minimum milliseconds between duplicate events with the same event_name.
+     * Prevents inflated analytics from event bubbling, double-bound listeners,
+     * or rapid-fire IntersectionObserver callbacks.
+     * Set to 0 to disable dedup. Default: 300ms.
+     */
+    eventDedupMs?: number;
 }
 /**
  * Analytics hook return type

package/dist/{index-jomBa89d.d.ts → index-CYS_FzSf.d.ts}

@@ -614,6 +614,13 @@ interface UseAnalyticsOptions {
     anonymousStorageKey?: string;
     /** Use v2 enhanced tracking (default: true) */
     useV2?: boolean;
+    /**
+     * Minimum milliseconds between duplicate events with the same event_name.
+     * Prevents inflated analytics from event bubbling, double-bound listeners,
+     * or rapid-fire IntersectionObserver callbacks.
+     * Set to 0 to disable dedup. Default: 300ms.
+     */
+    eventDedupMs?: number;
 }
 /**
  * Analytics hook return type

package/dist/index.d.mts

@@ -2,8 +2,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import { ScaleMuleClient } from './client.mjs';
 export { ClientConfig, RequestOptions, createClient } from './client.mjs';
-import { S as ScaleMuleConfig, U as User, L as LoginResponse, A as ApiError, a as UseAuthReturn, b as UseBillingReturn, c as ListFilesParams, d as UseContentReturn, e as UseUserReturn, f as UseAnalyticsOptions, g as UseAnalyticsReturn } from './index-jomBa89d.mjs';
-export { a2 as AccountBalance, a9 as AnalyticsEvent, k as ApiResponse, af as BatchTrackRequest, a3 as BillingPayment, a5 as BillingPayout, a4 as BillingRefund, a7 as BillingTransaction, r as ChangeEmailRequest, C as ChangePasswordRequest, $ as ClientContext, a1 as ConnectedAccount, D as DeviceFingerprint, ac as DeviceInfo, ad as EnhancedAnalyticsEvent, F as ForgotPasswordRequest, x as LinkedAccount, T as ListFilesResponse, n as LoginDeviceInfo, l as LoginRequest, m as LoginResponseWithMFA, o as LoginRiskInfo, G as MFAChallengeResponse, M as MFAMethod, B as MFASMSSetupResponse, y as MFASetupRequest, H as MFAStatus, z as MFATOTPSetupResponse, E as MFAVerifyRequest, v as OAuthCallbackRequest, w as OAuthCallbackResponse, t as OAuthConfig, O as OAuthProvider, u as OAuthStartResponse, aa as PageViewData, a6 as PayoutSchedule, K as PhoneLoginRequest, I as PhoneSendCodeRequest, J as PhoneVerifyRequest, P as Profile, p as RefreshResponse, R as RegisterRequest, q as ResetPasswordRequest, h as ScaleMuleApiError, i as ScaleMuleEnvironment, s as Session, _ as SignedUploadCompleteRequest, Y as SignedUploadRequest, Z as SignedUploadResponse, X as SignedUploadUrl, j as StorageAdapter, N as StorageFile, ae as TrackEventResponse, a8 as TransactionSummary, ab as UTMParams, a0 as UpdateProfileRequest, Q as UploadOptions, W as UploadResponse, V as VerifyEmailRequest } from './index-jomBa89d.mjs';
+import { S as ScaleMuleConfig, U as User, L as LoginResponse, A as ApiError, a as UseAuthReturn, b as UseBillingReturn, c as ListFilesParams, d as UseContentReturn, e as UseUserReturn, f as UseAnalyticsOptions, g as UseAnalyticsReturn } from './index-CYS_FzSf.mjs';
+export { a2 as AccountBalance, a9 as AnalyticsEvent, k as ApiResponse, af as BatchTrackRequest, a3 as BillingPayment, a5 as BillingPayout, a4 as BillingRefund, a7 as BillingTransaction, r as ChangeEmailRequest, C as ChangePasswordRequest, $ as ClientContext, a1 as ConnectedAccount, D as DeviceFingerprint, ac as DeviceInfo, ad as EnhancedAnalyticsEvent, F as ForgotPasswordRequest, x as LinkedAccount, T as ListFilesResponse, n as LoginDeviceInfo, l as LoginRequest, m as LoginResponseWithMFA, o as LoginRiskInfo, G as MFAChallengeResponse, M as MFAMethod, B as MFASMSSetupResponse, y as MFASetupRequest, H as MFAStatus, z as MFATOTPSetupResponse, E as MFAVerifyRequest, v as OAuthCallbackRequest, w as OAuthCallbackResponse, t as OAuthConfig, O as OAuthProvider, u as OAuthStartResponse, aa as PageViewData, a6 as PayoutSchedule, K as PhoneLoginRequest, I as PhoneSendCodeRequest, J as PhoneVerifyRequest, P as Profile, p as RefreshResponse, R as RegisterRequest, q as ResetPasswordRequest, h as ScaleMuleApiError, i as ScaleMuleEnvironment, s as Session, _ as SignedUploadCompleteRequest, Y as SignedUploadRequest, Z as SignedUploadResponse, X as SignedUploadUrl, j as StorageAdapter, N as StorageFile, ae as TrackEventResponse, a8 as TransactionSummary, ab as UTMParams, a0 as UpdateProfileRequest, Q as UploadOptions, W as UploadResponse, V as VerifyEmailRequest } from './index-CYS_FzSf.mjs';
 
 interface ScaleMuleContextValue {
     /** The API client instance */

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import { ScaleMuleClient } from './client.js';
 export { ClientConfig, RequestOptions, createClient } from './client.js';
-import { S as ScaleMuleConfig, U as User, L as LoginResponse, A as ApiError, a as UseAuthReturn, b as UseBillingReturn, c as ListFilesParams, d as UseContentReturn, e as UseUserReturn, f as UseAnalyticsOptions, g as UseAnalyticsReturn } from './index-jomBa89d.js';
-export { a2 as AccountBalance, a9 as AnalyticsEvent, k as ApiResponse, af as BatchTrackRequest, a3 as BillingPayment, a5 as BillingPayout, a4 as BillingRefund, a7 as BillingTransaction, r as ChangeEmailRequest, C as ChangePasswordRequest, $ as ClientContext, a1 as ConnectedAccount, D as DeviceFingerprint, ac as DeviceInfo, ad as EnhancedAnalyticsEvent, F as ForgotPasswordRequest, x as LinkedAccount, T as ListFilesResponse, n as LoginDeviceInfo, l as LoginRequest, m as LoginResponseWithMFA, o as LoginRiskInfo, G as MFAChallengeResponse, M as MFAMethod, B as MFASMSSetupResponse, y as MFASetupRequest, H as MFAStatus, z as MFATOTPSetupResponse, E as MFAVerifyRequest, v as OAuthCallbackRequest, w as OAuthCallbackResponse, t as OAuthConfig, O as OAuthProvider, u as OAuthStartResponse, aa as PageViewData, a6 as PayoutSchedule, K as PhoneLoginRequest, I as PhoneSendCodeRequest, J as PhoneVerifyRequest, P as Profile, p as RefreshResponse, R as RegisterRequest, q as ResetPasswordRequest, h as ScaleMuleApiError, i as ScaleMuleEnvironment, s as Session, _ as SignedUploadCompleteRequest, Y as SignedUploadRequest, Z as SignedUploadResponse, X as SignedUploadUrl, j as StorageAdapter, N as StorageFile, ae as TrackEventResponse, a8 as TransactionSummary, ab as UTMParams, a0 as UpdateProfileRequest, Q as UploadOptions, W as UploadResponse, V as VerifyEmailRequest } from './index-jomBa89d.js';
+import { S as ScaleMuleConfig, U as User, L as LoginResponse, A as ApiError, a as UseAuthReturn, b as UseBillingReturn, c as ListFilesParams, d as UseContentReturn, e as UseUserReturn, f as UseAnalyticsOptions, g as UseAnalyticsReturn } from './index-CYS_FzSf.js';
+export { a2 as AccountBalance, a9 as AnalyticsEvent, k as ApiResponse, af as BatchTrackRequest, a3 as BillingPayment, a5 as BillingPayout, a4 as BillingRefund, a7 as BillingTransaction, r as ChangeEmailRequest, C as ChangePasswordRequest, $ as ClientContext, a1 as ConnectedAccount, D as DeviceFingerprint, ac as DeviceInfo, ad as EnhancedAnalyticsEvent, F as ForgotPasswordRequest, x as LinkedAccount, T as ListFilesResponse, n as LoginDeviceInfo, l as LoginRequest, m as LoginResponseWithMFA, o as LoginRiskInfo, G as MFAChallengeResponse, M as MFAMethod, B as MFASMSSetupResponse, y as MFASetupRequest, H as MFAStatus, z as MFATOTPSetupResponse, E as MFAVerifyRequest, v as OAuthCallbackRequest, w as OAuthCallbackResponse, t as OAuthConfig, O as OAuthProvider, u as OAuthStartResponse, aa as PageViewData, a6 as PayoutSchedule, K as PhoneLoginRequest, I as PhoneSendCodeRequest, J as PhoneVerifyRequest, P as Profile, p as RefreshResponse, R as RegisterRequest, q as ResetPasswordRequest, h as ScaleMuleApiError, i as ScaleMuleEnvironment, s as Session, _ as SignedUploadCompleteRequest, Y as SignedUploadRequest, Z as SignedUploadResponse, X as SignedUploadUrl, j as StorageAdapter, N as StorageFile, ae as TrackEventResponse, a8 as TransactionSummary, ab as UTMParams, a0 as UpdateProfileRequest, Q as UploadOptions, W as UploadResponse, V as VerifyEmailRequest } from './index-CYS_FzSf.js';
 
 interface ScaleMuleContextValue {
     /** The API client instance */

package/dist/index.js

@@ -2412,6 +2412,44 @@ function useRealtime(options = {}) {
     [status, error, connect, disconnect, subscribe, send, lastMessage]
   );
 }
+
+// src/hooks/event-dedup.ts
+var DEFAULT_EVENT_DEDUP_MS = 300;
+var DEDUP_MAP_MAX = 200;
+var _eventLastFired = typeof window !== "undefined" ? /* @__PURE__ */ new Map() : null;
+function dedupKey(eventName, properties) {
+  if (!properties) return eventName;
+  const keys = Object.keys(properties);
+  if (keys.length === 0) return eventName;
+  let parts = eventName;
+  for (let i = 0, len = keys.length; i < len; i++) {
+    const k = keys[i];
+    const v = properties[k];
+    if (v === null || v === void 0) {
+      parts += `|${k}=`;
+    } else if (typeof v === "object") {
+      parts += `|${k}=[obj]`;
+    } else {
+      parts += `|${k}=${String(v)}`;
+    }
+  }
+  return parts;
+}
+function shouldDedup(eventName, cooldownMs, properties) {
+  if (!_eventLastFired || cooldownMs <= 0) return false;
+  const now = Date.now();
+  const key = dedupKey(eventName, properties);
+  const last = _eventLastFired.get(key);
+  if (last !== void 0 && now - last < cooldownMs) return true;
+  if (_eventLastFired.size >= DEDUP_MAP_MAX) {
+    const oldest = _eventLastFired.keys().next().value;
+    if (oldest !== void 0) _eventLastFired.delete(oldest);
+  }
+  _eventLastFired.set(key, now);
+  return false;
+}
+
+// src/hooks/useAnalytics.ts
 function generateUUID() {
   return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
     const r = Math.random() * 16 | 0;
@@ -2560,7 +2598,8 @@ function useAnalytics(options = {}) {
     autoGenerateSessionId = true,
     sessionStorageKey = "sm_session_id",
     anonymousStorageKey = "sm_anonymous_id",
-    useV2 = true
+    useV2 = true,
+    eventDedupMs = DEFAULT_EVENT_DEDUP_MS
   } = options;
   const shouldAutoCaptureUtmParams = autoCaptureUtmParams ?? autoCapturUtmParams ?? true;
   const { client, user, analyticsProxyUrl, publishableKey, gatewayUrl } = useScaleMule();
@@ -2706,6 +2745,9 @@ function useAnalytics(options = {}) {
   sendEventRef.current = sendEvent;
   const trackEvent = react.useCallback(
     async (event) => {
+      if (shouldDedup(event.event_name, eventDedupMs, event.properties)) {
+        return { tracked: 0, session_id: sessionIdRef.current || void 0 };
+      }
       setError(null);
       setLoading(true);
       try {
@@ -2725,7 +2767,7 @@ function useAnalytics(options = {}) {
       }
     },
     // Note: idsReady removed - we use ref to keep callback stable
-    [sendEvent]
+    [sendEvent, eventDedupMs]
   );
   const trackPageView = react.useCallback(
     async (data) => {

package/dist/index.mjs

@@ -2410,6 +2410,44 @@ function useRealtime(options = {}) {
     [status, error, connect, disconnect, subscribe, send, lastMessage]
   );
 }
+
+// src/hooks/event-dedup.ts
+var DEFAULT_EVENT_DEDUP_MS = 300;
+var DEDUP_MAP_MAX = 200;
+var _eventLastFired = typeof window !== "undefined" ? /* @__PURE__ */ new Map() : null;
+function dedupKey(eventName, properties) {
+  if (!properties) return eventName;
+  const keys = Object.keys(properties);
+  if (keys.length === 0) return eventName;
+  let parts = eventName;
+  for (let i = 0, len = keys.length; i < len; i++) {
+    const k = keys[i];
+    const v = properties[k];
+    if (v === null || v === void 0) {
+      parts += `|${k}=`;
+    } else if (typeof v === "object") {
+      parts += `|${k}=[obj]`;
+    } else {
+      parts += `|${k}=${String(v)}`;
+    }
+  }
+  return parts;
+}
+function shouldDedup(eventName, cooldownMs, properties) {
+  if (!_eventLastFired || cooldownMs <= 0) return false;
+  const now = Date.now();
+  const key = dedupKey(eventName, properties);
+  const last = _eventLastFired.get(key);
+  if (last !== void 0 && now - last < cooldownMs) return true;
+  if (_eventLastFired.size >= DEDUP_MAP_MAX) {
+    const oldest = _eventLastFired.keys().next().value;
+    if (oldest !== void 0) _eventLastFired.delete(oldest);
+  }
+  _eventLastFired.set(key, now);
+  return false;
+}
+
+// src/hooks/useAnalytics.ts
 function generateUUID() {
   return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
     const r = Math.random() * 16 | 0;
@@ -2558,7 +2596,8 @@ function useAnalytics(options = {}) {
     autoGenerateSessionId = true,
     sessionStorageKey = "sm_session_id",
     anonymousStorageKey = "sm_anonymous_id",
-    useV2 = true
+    useV2 = true,
+    eventDedupMs = DEFAULT_EVENT_DEDUP_MS
   } = options;
   const shouldAutoCaptureUtmParams = autoCaptureUtmParams ?? autoCapturUtmParams ?? true;
   const { client, user, analyticsProxyUrl, publishableKey, gatewayUrl } = useScaleMule();
@@ -2704,6 +2743,9 @@ function useAnalytics(options = {}) {
   sendEventRef.current = sendEvent;
   const trackEvent = useCallback(
     async (event) => {
+      if (shouldDedup(event.event_name, eventDedupMs, event.properties)) {
+        return { tracked: 0, session_id: sessionIdRef.current || void 0 };
+      }
       setError(null);
       setLoading(true);
       try {
@@ -2723,7 +2765,7 @@ function useAnalytics(options = {}) {
       }
     },
     // Note: idsReady removed - we use ref to keep callback stable
-    [sendEvent]
+    [sendEvent, eventDedupMs]
   );
   const trackPageView = useCallback(
     async (data) => {

package/dist/server/index.d.mts

@@ -1,6 +1,6 @@
-import { S as ServerConfig } from '../webhook-handler-aT2C5z2y.mjs';
-export { a as ScaleMuleServer, e as VideoFailedEvent, V as VideoReadyEvent, g as VideoTranscodedEvent, f as VideoUploadedEvent, W as WebhookEvent, h as WebhookRoutesConfig, c as createServerClient, i as createWebhookHandler, d as createWebhookRoutes, p as parseWebhookEvent, b as registerVideoWebhook, r as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-aT2C5z2y.mjs';
-import { $ as ClientContext, A as ApiError } from '../index-jomBa89d.mjs';
+import { S as ServerConfig } from '../webhook-handler-BlklRG--.mjs';
+export { a as ScaleMuleServer, e as VideoFailedEvent, V as VideoReadyEvent, g as VideoTranscodedEvent, f as VideoUploadedEvent, W as WebhookEvent, h as WebhookRoutesConfig, c as createServerClient, i as createWebhookHandler, d as createWebhookRoutes, p as parseWebhookEvent, b as registerVideoWebhook, r as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-BlklRG--.mjs';
+import { $ as ClientContext, A as ApiError } from '../index-CYS_FzSf.mjs';
 import { NextRequest, NextResponse } from 'next/server';
 
 /**
@@ -94,6 +94,13 @@ declare function extractClientContextFromReq(req: IncomingMessageLike): ClientCo
  * @internal
  */
 declare function buildClientContextHeaders(context: ClientContext | undefined): Record<string, string>;
+/**
+ * Build feature-flag evaluation context from forwarded client context.
+ *
+ * This keeps server-side flag evaluation aligned with targeting rules that use
+ * `ip_address`, while letting callers merge any additional attributes they need.
+ */
+declare function buildFlagContext(clientContext: Pick<ClientContext, 'ip'> | undefined, extraContext?: Record<string, unknown>): Record<string, unknown>;
 
 /**
  * Cookie Utilities for Secure Session Management
@@ -262,6 +269,27 @@ declare function createAuthRoutes(config?: AuthRoutesConfig): {
     DELETE: RouteHandler;
     PATCH: RouteHandler;
 };
+interface AnalyticsTrackingGateConfig {
+    /** Feature flag key used to decide whether to forward analytics */
+    flagKey: string;
+    /** Feature flag environment (default: 'prod') */
+    environment?: string;
+    /**
+     * When true, analytics continues if flag evaluation fails.
+     * Default: true
+     */
+    failOpen?: boolean;
+    /**
+     * Build feature-flag evaluation context from the inbound analytics request.
+     * Defaults to { ip_address, user_id, anonymous_id, session_id, event_name, page_url }
+     * when those values are present.
+     */
+    buildContext?: (args: {
+        body: Record<string, unknown>;
+        clientContext: ClientContext;
+        request: Request;
+    }) => Record<string, unknown>;
+}
 interface AnalyticsRoutesConfig {
     /** Server client config (optional if using env vars) */
     client?: Partial<ServerConfig>;
@@ -276,6 +304,12 @@ interface AnalyticsRoutesConfig {
      * Default: false (uses catch-all route pattern)
      */
     simpleProxy?: boolean;
+    /**
+     * Optional feature flag gate that suppresses analytics forwarding when the
+     * evaluated flag returns false. Useful for test users, internal IPs, or
+     * staged rollouts without adding app-specific proxy logic.
+     */
+    trackingGate?: AnalyticsTrackingGateConfig;
 }
 /**
  * Create analytics API route handlers
@@ -906,4 +940,4 @@ declare function invalidateBundleCache(key?: string): void;
  */
 declare function prefetchBundles(keys: string[]): Promise<void>;
 
-export { type AnalyticsRoutesConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type HandlerContext, type HandlerOptions, type MySqlBundle, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PostgresBundle, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, ScaleMuleError, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, prefetchBundles, prefetchSecrets, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, withAuth, withCSRFProtection, withCSRFToken, withSession };
+export { type AnalyticsRoutesConfig, type AnalyticsTrackingGateConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type HandlerContext, type HandlerOptions, type MySqlBundle, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PostgresBundle, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, ScaleMuleError, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, buildFlagContext, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, prefetchBundles, prefetchSecrets, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, withAuth, withCSRFProtection, withCSRFToken, withSession };

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
-import { S as ServerConfig } from '../webhook-handler-Dok4jfub.js';
-export { a as ScaleMuleServer, e as VideoFailedEvent, V as VideoReadyEvent, g as VideoTranscodedEvent, f as VideoUploadedEvent, W as WebhookEvent, h as WebhookRoutesConfig, c as createServerClient, i as createWebhookHandler, d as createWebhookRoutes, p as parseWebhookEvent, b as registerVideoWebhook, r as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-Dok4jfub.js';
-import { $ as ClientContext, A as ApiError } from '../index-jomBa89d.js';
+import { S as ServerConfig } from '../webhook-handler-DHCE2Utl.js';
+export { a as ScaleMuleServer, e as VideoFailedEvent, V as VideoReadyEvent, g as VideoTranscodedEvent, f as VideoUploadedEvent, W as WebhookEvent, h as WebhookRoutesConfig, c as createServerClient, i as createWebhookHandler, d as createWebhookRoutes, p as parseWebhookEvent, b as registerVideoWebhook, r as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-DHCE2Utl.js';
+import { $ as ClientContext, A as ApiError } from '../index-CYS_FzSf.js';
 import { NextRequest, NextResponse } from 'next/server';
 
 /**
@@ -94,6 +94,13 @@ declare function extractClientContextFromReq(req: IncomingMessageLike): ClientCo
  * @internal
  */
 declare function buildClientContextHeaders(context: ClientContext | undefined): Record<string, string>;
+/**
+ * Build feature-flag evaluation context from forwarded client context.
+ *
+ * This keeps server-side flag evaluation aligned with targeting rules that use
+ * `ip_address`, while letting callers merge any additional attributes they need.
+ */
+declare function buildFlagContext(clientContext: Pick<ClientContext, 'ip'> | undefined, extraContext?: Record<string, unknown>): Record<string, unknown>;
 
 /**
  * Cookie Utilities for Secure Session Management
@@ -262,6 +269,27 @@ declare function createAuthRoutes(config?: AuthRoutesConfig): {
     DELETE: RouteHandler;
     PATCH: RouteHandler;
 };
+interface AnalyticsTrackingGateConfig {
+    /** Feature flag key used to decide whether to forward analytics */
+    flagKey: string;
+    /** Feature flag environment (default: 'prod') */
+    environment?: string;
+    /**
+     * When true, analytics continues if flag evaluation fails.
+     * Default: true
+     */
+    failOpen?: boolean;
+    /**
+     * Build feature-flag evaluation context from the inbound analytics request.
+     * Defaults to { ip_address, user_id, anonymous_id, session_id, event_name, page_url }
+     * when those values are present.
+     */
+    buildContext?: (args: {
+        body: Record<string, unknown>;
+        clientContext: ClientContext;
+        request: Request;
+    }) => Record<string, unknown>;
+}
 interface AnalyticsRoutesConfig {
     /** Server client config (optional if using env vars) */
     client?: Partial<ServerConfig>;
@@ -276,6 +304,12 @@ interface AnalyticsRoutesConfig {
      * Default: false (uses catch-all route pattern)
      */
     simpleProxy?: boolean;
+    /**
+     * Optional feature flag gate that suppresses analytics forwarding when the
+     * evaluated flag returns false. Useful for test users, internal IPs, or
+     * staged rollouts without adding app-specific proxy logic.
+     */
+    trackingGate?: AnalyticsTrackingGateConfig;
 }
 /**
  * Create analytics API route handlers
@@ -906,4 +940,4 @@ declare function invalidateBundleCache(key?: string): void;
  */
 declare function prefetchBundles(keys: string[]): Promise<void>;
 
-export { type AnalyticsRoutesConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type HandlerContext, type HandlerOptions, type MySqlBundle, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PostgresBundle, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, ScaleMuleError, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, prefetchBundles, prefetchSecrets, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, withAuth, withCSRFProtection, withCSRFToken, withSession };
+export { type AnalyticsRoutesConfig, type AnalyticsTrackingGateConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type HandlerContext, type HandlerOptions, type MySqlBundle, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PostgresBundle, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, ScaleMuleError, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, buildFlagContext, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, prefetchBundles, prefetchSecrets, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, withAuth, withCSRFProtection, withCSRFToken, withSession };

package/dist/server/index.js

@@ -159,6 +159,13 @@ function buildClientContextHeaders(context) {
   }
   return headers2;
 }
+function buildFlagContext(clientContext, extraContext = {}) {
+  const context = { ...extraContext };
+  if (clientContext?.ip && context.ip_address === void 0) {
+    context.ip_address = clientContext.ip;
+  }
+  return context;
+}
 
 // src/server/client.ts
 var GATEWAY_URLS = {
@@ -1385,8 +1392,50 @@ function createAuthRoutes(config = {}) {
   };
   return { GET, POST, DELETE, PATCH };
 }
+function getPrimaryTrackingContextSource(body) {
+  if (Array.isArray(body.events)) {
+    const firstEvent = body.events.find((event) => event && typeof event === "object" && !Array.isArray(event));
+    if (firstEvent && typeof firstEvent === "object" && !Array.isArray(firstEvent)) {
+      return firstEvent;
+    }
+  }
+  return body;
+}
+function buildDefaultTrackingGateContext(args) {
+  const source = getPrimaryTrackingContextSource(args.body);
+  const extraContext = {};
+  for (const key of ["user_id", "anonymous_id", "session_id", "event_name", "page_url"]) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim()) {
+      extraContext[key] = value;
+    }
+  }
+  return buildFlagContext(args.clientContext, extraContext);
+}
 function createAnalyticsRoutes(config = {}) {
   const sm = createServerClient(config.client);
+  const shouldSuppressTracking = async (body, clientContext, request) => {
+    const gate = config.trackingGate;
+    if (!gate) {
+      return false;
+    }
+    try {
+      const contextBuilder = gate.buildContext || ((args) => buildDefaultTrackingGateContext(args));
+      const evaluation = await sm.flags.evaluate(
+        gate.flagKey,
+        contextBuilder({ body, clientContext, request }) || {},
+        gate.environment || "prod",
+        { clientContext }
+      );
+      return evaluation?.value === false;
+    } catch (err) {
+      if (gate.failOpen === false) {
+        console.warn(`[ScaleMule Analytics] Tracking gate blocked "${gate.flagKey}" after evaluation failure`, err);
+        return true;
+      }
+      return false;
+    }
+  };
   const handleTrackEvent = async (body, clientContext) => {
     const {
       event_name,
@@ -1469,8 +1518,12 @@ function createAnalyticsRoutes(config = {}) {
   };
   const POST = async (request, context) => {
     try {
-      const body = await request.json().catch(() => ({}));
+      const rawBody = await request.json().catch(() => ({}));
+      const body = rawBody && typeof rawBody === "object" && !Array.isArray(rawBody) ? rawBody : {};
       const clientContext = extractClientContext(request);
+      if (await shouldSuppressTracking(body, clientContext, request)) {
+        return successResponse({ tracked: 0, suppressed: true }, 202);
+      }
       if (config.simpleProxy) {
         return handleTrackEvent(body, clientContext);
       }
@@ -1515,7 +1568,13 @@ function createAnalyticsRoutes(config = {}) {
           let pageViewResult;
           try {
             pageViewResult = await sm.analytics.trackPageView(
-              { page_url, page_title, referrer, session_id, user_id },
+              {
+                page_url,
+                page_title,
+                referrer,
+                session_id,
+                user_id
+              },
               { clientContext }
             );
           } catch (err) {
@@ -2153,6 +2212,7 @@ exports.ScaleMuleServer = ScaleMuleServer;
 exports.USER_ID_COOKIE_NAME = USER_ID_COOKIE_NAME;
 exports.apiHandler = apiHandler;
 exports.buildClientContextHeaders = buildClientContextHeaders;
+exports.buildFlagContext = buildFlagContext;
 exports.clearOAuthState = clearOAuthState;
 exports.clearSession = clearSession;
 exports.configureBundles = configureBundles;

package/dist/server/index.mjs

@@ -157,6 +157,13 @@ function buildClientContextHeaders(context) {
   }
   return headers2;
 }
+function buildFlagContext(clientContext, extraContext = {}) {
+  const context = { ...extraContext };
+  if (clientContext?.ip && context.ip_address === void 0) {
+    context.ip_address = clientContext.ip;
+  }
+  return context;
+}
 
 // src/server/client.ts
 var GATEWAY_URLS = {
@@ -1383,8 +1390,50 @@ function createAuthRoutes(config = {}) {
   };
   return { GET, POST, DELETE, PATCH };
 }
+function getPrimaryTrackingContextSource(body) {
+  if (Array.isArray(body.events)) {
+    const firstEvent = body.events.find((event) => event && typeof event === "object" && !Array.isArray(event));
+    if (firstEvent && typeof firstEvent === "object" && !Array.isArray(firstEvent)) {
+      return firstEvent;
+    }
+  }
+  return body;
+}
+function buildDefaultTrackingGateContext(args) {
+  const source = getPrimaryTrackingContextSource(args.body);
+  const extraContext = {};
+  for (const key of ["user_id", "anonymous_id", "session_id", "event_name", "page_url"]) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim()) {
+      extraContext[key] = value;
+    }
+  }
+  return buildFlagContext(args.clientContext, extraContext);
+}
 function createAnalyticsRoutes(config = {}) {
   const sm = createServerClient(config.client);
+  const shouldSuppressTracking = async (body, clientContext, request) => {
+    const gate = config.trackingGate;
+    if (!gate) {
+      return false;
+    }
+    try {
+      const contextBuilder = gate.buildContext || ((args) => buildDefaultTrackingGateContext(args));
+      const evaluation = await sm.flags.evaluate(
+        gate.flagKey,
+        contextBuilder({ body, clientContext, request }) || {},
+        gate.environment || "prod",
+        { clientContext }
+      );
+      return evaluation?.value === false;
+    } catch (err) {
+      if (gate.failOpen === false) {
+        console.warn(`[ScaleMule Analytics] Tracking gate blocked "${gate.flagKey}" after evaluation failure`, err);
+        return true;
+      }
+      return false;
+    }
+  };
   const handleTrackEvent = async (body, clientContext) => {
     const {
       event_name,
@@ -1467,8 +1516,12 @@ function createAnalyticsRoutes(config = {}) {
   };
   const POST = async (request, context) => {
     try {
-      const body = await request.json().catch(() => ({}));
+      const rawBody = await request.json().catch(() => ({}));
+      const body = rawBody && typeof rawBody === "object" && !Array.isArray(rawBody) ? rawBody : {};
       const clientContext = extractClientContext(request);
+      if (await shouldSuppressTracking(body, clientContext, request)) {
+        return successResponse({ tracked: 0, suppressed: true }, 202);
+      }
       if (config.simpleProxy) {
         return handleTrackEvent(body, clientContext);
       }
@@ -1513,7 +1566,13 @@ function createAnalyticsRoutes(config = {}) {
           let pageViewResult;
           try {
             pageViewResult = await sm.analytics.trackPageView(
-              { page_url, page_title, referrer, session_id, user_id },
+              {
+                page_url,
+                page_title,
+                referrer,
+                session_id,
+                user_id
+              },
               { clientContext }
             );
           } catch (err) {
@@ -2142,4 +2201,4 @@ async function prefetchBundles(keys) {
   await Promise.all(keys.map((key) => getBundle(key)));
 }
 
-export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, OAUTH_STATE_COOKIE_NAME, SESSION_COOKIE_NAME, ScaleMuleError, ScaleMuleServer, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, createServerClient, createWebhookHandler, createWebhookRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, parseWebhookEvent, prefetchBundles, prefetchSecrets, registerVideoWebhook, requireAppSecret, requireBundle, requireSession, resolveGatewayUrl, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, verifyWebhookSignature, withAuth, withCSRFProtection, withCSRFToken, withSession };
+export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, OAUTH_STATE_COOKIE_NAME, SESSION_COOKIE_NAME, ScaleMuleError, ScaleMuleServer, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, buildFlagContext, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, createServerClient, createWebhookHandler, createWebhookRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, parseWebhookEvent, prefetchBundles, prefetchSecrets, registerVideoWebhook, requireAppSecret, requireBundle, requireSession, resolveGatewayUrl, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, verifyWebhookSignature, withAuth, withCSRFProtection, withCSRFToken, withSession };

package/dist/server/webhook-handler.d.mts

@@ -1,2 +1,2 @@
-export { i as createWebhookHandler } from '../webhook-handler-aT2C5z2y.mjs';
-import '../index-jomBa89d.mjs';
+export { i as createWebhookHandler } from '../webhook-handler-BlklRG--.mjs';
+import '../index-CYS_FzSf.mjs';

package/dist/server/webhook-handler.d.ts

@@ -1,2 +1,2 @@
-export { i as createWebhookHandler } from '../webhook-handler-Dok4jfub.js';
-import '../index-jomBa89d.js';
+export { i as createWebhookHandler } from '../webhook-handler-DHCE2Utl.js';
+import '../index-CYS_FzSf.js';

package/dist/testing.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { U as User, N as StorageFile, A as ApiError } from './index-jomBa89d.mjs';
+import { U as User, N as StorageFile, A as ApiError } from './index-CYS_FzSf.mjs';
 
 interface MockUserOptions {
     id?: string;

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { U as User, N as StorageFile, A as ApiError } from './index-jomBa89d.js';
+import { U as User, N as StorageFile, A as ApiError } from './index-CYS_FzSf.js';
 
 interface MockUserOptions {
     id?: string;

package/dist/{webhook-handler-aT2C5z2y.d.mts → webhook-handler-BlklRG--.d.mts}

@@ -1,4 +1,4 @@
-import { R as RegisterRequest, $ as ClientContext, U as User, l as LoginRequest, L as LoginResponse, c as ListFilesParams, T as ListFilesResponse, N as StorageFile, W as UploadResponse } from './index-jomBa89d.mjs';
+import { R as RegisterRequest, $ as ClientContext, U as User, l as LoginRequest, L as LoginResponse, c as ListFilesParams, T as ListFilesResponse, N as StorageFile, W as UploadResponse } from './index-CYS_FzSf.mjs';
 
 /**
  * Server-Side ScaleMule Client

package/dist/{webhook-handler-Dok4jfub.d.ts → webhook-handler-DHCE2Utl.d.ts}

@@ -1,4 +1,4 @@
-import { R as RegisterRequest, $ as ClientContext, U as User, l as LoginRequest, L as LoginResponse, c as ListFilesParams, T as ListFilesResponse, N as StorageFile, W as UploadResponse } from './index-jomBa89d.js';
+import { R as RegisterRequest, $ as ClientContext, U as User, l as LoginRequest, L as LoginResponse, c as ListFilesParams, T as ListFilesResponse, N as StorageFile, W as UploadResponse } from './index-CYS_FzSf.js';
 
 /**
  * Server-Side ScaleMule Client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalemule/nextjs",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "ScaleMule SDK for Next.js applications - authentication, storage, and user management",
   "main": "dist/index.js",
   "module": "dist/index.mjs",