@scalemule/nextjs 0.0.25 → 0.0.26

package/dist/server/index.d.mts

@@ -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

@@ -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/package.json

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