@scalemule/nextjs 0.0.25 → 0.0.27

package/dist/client.d.mts

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

package/dist/client.d.ts

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

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

@@ -533,12 +533,36 @@ interface UTMParams {
     utm_source?: string;
     /** Marketing medium (e.g., 'cpc', 'email', 'social') */
     utm_medium?: string;
-    /** Campaign name */
+    /** Campaign name or ID */
     utm_campaign?: string;
     /** Search term for paid search */
     utm_term?: string;
     /** Content identifier for A/B testing */
     utm_content?: string;
+    /** Ad group name or ID */
+    utm_adgroup?: string;
+    /** Google Ads click ID (auto-appended by Google) */
+    gclid?: string;
+    /** Google Ads click ID for iOS (app attribution) */
+    gbraid?: string;
+    /** Google Ads click ID for web (cross-domain) */
+    wbraid?: string;
+    /** Facebook/Meta click ID (auto-appended by Meta) */
+    fbclid?: string;
+    /** Google Ads campaign ID (via ValueTrack {campaignid}) */
+    gad_campaignid?: string;
+    /** Google Ads ad group ID (via ValueTrack {adgroupid}) */
+    gad_adgroupid?: string;
+    /** Google Ads network: g=search, d=display, y=youtube */
+    gad_network?: string;
+    /** Google Ads match type: b=broad, p=phrase, e=exact */
+    gad_matchtype?: string;
+    /** Google Ads device: m=mobile, c=desktop, t=tablet */
+    gad_device?: string;
+    /** Google Ads placement (display/youtube site) */
+    gad_placement?: string;
+    /** Google Ads source identifier */
+    gad_source?: string;
 }
 /**
  * Device information for analytics

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

@@ -533,12 +533,36 @@ interface UTMParams {
     utm_source?: string;
     /** Marketing medium (e.g., 'cpc', 'email', 'social') */
     utm_medium?: string;
-    /** Campaign name */
+    /** Campaign name or ID */
     utm_campaign?: string;
     /** Search term for paid search */
     utm_term?: string;
     /** Content identifier for A/B testing */
     utm_content?: string;
+    /** Ad group name or ID */
+    utm_adgroup?: string;
+    /** Google Ads click ID (auto-appended by Google) */
+    gclid?: string;
+    /** Google Ads click ID for iOS (app attribution) */
+    gbraid?: string;
+    /** Google Ads click ID for web (cross-domain) */
+    wbraid?: string;
+    /** Facebook/Meta click ID (auto-appended by Meta) */
+    fbclid?: string;
+    /** Google Ads campaign ID (via ValueTrack {campaignid}) */
+    gad_campaignid?: string;
+    /** Google Ads ad group ID (via ValueTrack {adgroupid}) */
+    gad_adgroupid?: string;
+    /** Google Ads network: g=search, d=display, y=youtube */
+    gad_network?: string;
+    /** Google Ads match type: b=broad, p=phrase, e=exact */
+    gad_matchtype?: string;
+    /** Google Ads device: m=mobile, c=desktop, t=tablet */
+    gad_device?: string;
+    /** Google Ads placement (display/youtube site) */
+    gad_placement?: string;
+    /** Google Ads source identifier */
+    gad_source?: string;
 }
 /**
  * Device information for analytics

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-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';
+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-DewTyMF2.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-DewTyMF2.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-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';
+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-DewTyMF2.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-DewTyMF2.js';
 
 interface ScaleMuleContextValue {
     /** The API client instance */

package/dist/index.js

@@ -2511,20 +2511,34 @@ function parseUtmParams() {
   const campaign = params.get("utm_campaign");
   const term = params.get("utm_term");
   const content = params.get("utm_content");
+  const adgroup = params.get("utm_adgroup");
   if (source) utm.utm_source = source;
   if (medium) utm.utm_medium = medium;
   if (campaign) utm.utm_campaign = campaign;
   if (term) utm.utm_term = term;
   if (content) utm.utm_content = content;
-  if (!utm.utm_source && (params.get("gclid") || params.get("gad_source") || params.get("wbraid") || params.get("gbraid"))) {
+  if (adgroup) utm.utm_adgroup = adgroup;
+  const gclid = params.get("gclid");
+  const gbraid = params.get("gbraid");
+  const wbraid = params.get("wbraid");
+  const fbclid = params.get("fbclid");
+  if (gclid) utm.gclid = gclid;
+  if (gbraid) utm.gbraid = gbraid;
+  if (wbraid) utm.wbraid = wbraid;
+  if (fbclid) utm.fbclid = fbclid;
+  const gadFields = ["gad_source", "gad_campaignid", "gad_adgroupid", "gad_network", "gad_matchtype", "gad_device", "gad_placement"];
+  for (const field of gadFields) {
+    const val = params.get(field);
+    if (val) utm[field] = val;
+  }
+  if (!utm.utm_source && (gclid || utm.gad_source || wbraid || gbraid)) {
     utm.utm_source = "google";
     utm.utm_medium = utm.utm_medium || "cpc";
-    const gadCampaign = params.get("gad_campaignid");
-    if (gadCampaign && !utm.utm_campaign) {
-      utm.utm_campaign = gadCampaign;
+    if (utm.gad_campaignid && !utm.utm_campaign) {
+      utm.utm_campaign = utm.gad_campaignid;
     }
   }
-  if (!utm.utm_source && params.get("fbclid")) {
+  if (!utm.utm_source && fbclid) {
     utm.utm_source = "facebook";
     utm.utm_medium = utm.utm_medium || "cpc";
   }

package/dist/index.mjs

@@ -2509,20 +2509,34 @@ function parseUtmParams() {
   const campaign = params.get("utm_campaign");
   const term = params.get("utm_term");
   const content = params.get("utm_content");
+  const adgroup = params.get("utm_adgroup");
   if (source) utm.utm_source = source;
   if (medium) utm.utm_medium = medium;
   if (campaign) utm.utm_campaign = campaign;
   if (term) utm.utm_term = term;
   if (content) utm.utm_content = content;
-  if (!utm.utm_source && (params.get("gclid") || params.get("gad_source") || params.get("wbraid") || params.get("gbraid"))) {
+  if (adgroup) utm.utm_adgroup = adgroup;
+  const gclid = params.get("gclid");
+  const gbraid = params.get("gbraid");
+  const wbraid = params.get("wbraid");
+  const fbclid = params.get("fbclid");
+  if (gclid) utm.gclid = gclid;
+  if (gbraid) utm.gbraid = gbraid;
+  if (wbraid) utm.wbraid = wbraid;
+  if (fbclid) utm.fbclid = fbclid;
+  const gadFields = ["gad_source", "gad_campaignid", "gad_adgroupid", "gad_network", "gad_matchtype", "gad_device", "gad_placement"];
+  for (const field of gadFields) {
+    const val = params.get(field);
+    if (val) utm[field] = val;
+  }
+  if (!utm.utm_source && (gclid || utm.gad_source || wbraid || gbraid)) {
     utm.utm_source = "google";
     utm.utm_medium = utm.utm_medium || "cpc";
-    const gadCampaign = params.get("gad_campaignid");
-    if (gadCampaign && !utm.utm_campaign) {
-      utm.utm_campaign = gadCampaign;
+    if (utm.gad_campaignid && !utm.utm_campaign) {
+      utm.utm_campaign = utm.gad_campaignid;
     }
   }
-  if (!utm.utm_source && params.get("fbclid")) {
+  if (!utm.utm_source && fbclid) {
     utm.utm_source = "facebook";
     utm.utm_medium = utm.utm_medium || "cpc";
   }

package/dist/server/index.d.mts

@@ -1,6 +1,6 @@
-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 { S as ServerConfig } from '../webhook-handler-DS0r_w4M.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-DS0r_w4M.mjs';
+import { $ as ClientContext, A as ApiError } from '../index-DewTyMF2.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-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 { S as ServerConfig } from '../webhook-handler-CQ2lZgy0.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-CQ2lZgy0.js';
+import { $ as ClientContext, A as ApiError } from '../index-DewTyMF2.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-BlklRG--.mjs';
-import '../index-CYS_FzSf.mjs';
+export { i as createWebhookHandler } from '../webhook-handler-DS0r_w4M.mjs';
+import '../index-DewTyMF2.mjs';

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

@@ -1,2 +1,2 @@
-export { i as createWebhookHandler } from '../webhook-handler-DHCE2Utl.js';
-import '../index-CYS_FzSf.js';
+export { i as createWebhookHandler } from '../webhook-handler-CQ2lZgy0.js';
+import '../index-DewTyMF2.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-CYS_FzSf.mjs';
+import { U as User, N as StorageFile, A as ApiError } from './index-DewTyMF2.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-CYS_FzSf.js';
+import { U as User, N as StorageFile, A as ApiError } from './index-DewTyMF2.js';
 
 interface MockUserOptions {
     id?: string;

package/dist/{webhook-handler-DHCE2Utl.d.ts → webhook-handler-CQ2lZgy0.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-CYS_FzSf.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-DewTyMF2.js';
 
 /**
  * Server-Side ScaleMule Client

package/dist/{webhook-handler-BlklRG--.d.mts → webhook-handler-DS0r_w4M.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-CYS_FzSf.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-DewTyMF2.mjs';
 
 /**
  * Server-Side ScaleMule Client

package/package.json

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