@scalemule/nextjs 0.1.30 → 0.1.31

package/README.md

@@ -95,6 +95,44 @@ For zero-config auth (reads from env vars):
 export { GET, POST, DELETE, PATCH } from '@scalemule/nextjs/server/auth'
 ```
 
+## Proxy Mode (keep API keys server-side)
+
+If you don't want a real ScaleMule API key in browser bundles, run the SDK in **proxy mode**: pass the literal sentinel string `'proxy-mode'` as `apiKey` and route all server-bound traffic through Next.js routes that hold the real `SCALEMULE_API_KEY` server-side. **Both** the auth route and the analytics route are required — without the analytics route, every `trackEvent` / `trackPageView` silently 401s against the gateway and the dashboard reads empty.
+
+```ts
+// app/api/auth/[...scalemule]/route.ts
+export { GET, POST, DELETE, PATCH } from '@scalemule/nextjs/server/auth'
+```
+
+```ts
+// app/api/analytics/event/route.ts
+import { NextRequest } from 'next/server'
+import { createAnalyticsRoutes } from '@scalemule/nextjs/server'
+
+const { POST: handler } = createAnalyticsRoutes({ simpleProxy: true })
+
+export const dynamic = 'force-dynamic'
+export function POST(req: NextRequest, ctx: { params: Promise<Record<string, string | string[]>> }) {
+  return handler(req, ctx)
+}
+```
+
+```tsx
+// app/layout.tsx
+<ScaleMuleProvider
+  apiKey="proxy-mode"
+  applicationId={process.env.SCALEMULE_APP_ID}
+  environment="prod"
+  gatewayUrl="https://api.scalemule.com"
+  authProxyUrl="/api/auth"
+  analyticsProxyUrl="/api/analytics/event"
+>
+  {children}
+</ScaleMuleProvider>
+```
+
+If `apiKey="proxy-mode"` is set without `analyticsProxyUrl` (and no `publishableKey`), `useAnalytics` emits a one-time dev console warning — that exact misconfig caused a silent-empty dashboard in production for one customer (Gistyo, app ID `019dda2a-c7d9-75a1-9258-12e4c48f1499`).
+
 ## Client-Side Provider
 
 ```tsx

package/dist/index.d.mts

@@ -245,6 +245,14 @@ interface ScaleMuleContextValue {
     authProxyUrl?: string;
     /** Publishable key for browser-safe operations (analytics) */
     publishableKey?: string;
+    /**
+     * The configured `apiKey` value. Exposed so hooks like `useAnalytics`
+     * can detect the proxy-mode sentinel (`'proxy-mode'`) and warn when
+     * the corresponding proxy route is missing — silently 401'ing on the
+     * fallback is the worst possible failure mode for an analytics path.
+     * Treat as read-only diagnostic; consumers should not pass it onward.
+     */
+    apiKey?: string;
     /** Gateway URL for direct API calls */
     gatewayUrl?: string;
     /** Configured environment ('dev' or 'prod') */

package/dist/index.d.ts

@@ -245,6 +245,14 @@ interface ScaleMuleContextValue {
     authProxyUrl?: string;
     /** Publishable key for browser-safe operations (analytics) */
     publishableKey?: string;
+    /**
+     * The configured `apiKey` value. Exposed so hooks like `useAnalytics`
+     * can detect the proxy-mode sentinel (`'proxy-mode'`) and warn when
+     * the corresponding proxy route is missing — silently 401'ing on the
+     * fallback is the worst possible failure mode for an analytics path.
+     * Treat as read-only diagnostic; consumers should not pass it onward.
+     */
+    apiKey?: string;
     /** Gateway URL for direct API calls */
     gatewayUrl?: string;
     /** Configured environment ('dev' or 'prod') */

package/dist/index.js

@@ -8924,13 +8924,14 @@ function ScaleMuleProvider({
       analyticsProxyUrl,
       authProxyUrl,
       publishableKey,
+      apiKey,
       gatewayUrl: resolvedGatewayUrl,
       environment: environment || void 0,
       enableAccountSwitcher,
       accountSwitcherPrivacy,
       bootstrapFlags
     }),
-    [client, money$1, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, effectiveMediaPolicy]
+    [client, money$1, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, apiKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, effectiveMediaPolicy]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(ScaleMuleContext.Provider, { value, children });
 }
@@ -11645,7 +11646,18 @@ function useAnalytics(options = {}) {
     eventDedupMs = DEFAULT_EVENT_DEDUP_MS
   } = options;
   const shouldAutoCaptureUtmParams = autoCaptureUtmParams ?? autoCapturUtmParams ?? true;
-  const { client, user, analyticsProxyUrl, publishableKey, gatewayUrl } = useScaleMule();
+  const { client, user, analyticsProxyUrl, publishableKey, apiKey, gatewayUrl } = useScaleMule();
+  const proxyModeMisconfigWarnedRef = React.useRef(false);
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    if (proxyModeMisconfigWarnedRef.current) return;
+    if (apiKey === "proxy-mode" && !analyticsProxyUrl && !publishableKey) {
+      proxyModeMisconfigWarnedRef.current = true;
+      console.warn(
+        '[ScaleMule] useAnalytics: apiKey="proxy-mode" but neither `analyticsProxyUrl` nor `publishableKey` is configured. Every trackEvent / trackPageView will silently 401 against the gateway. Add an analytics proxy route (createAnalyticsRoutes({ simpleProxy: true })) and pass `analyticsProxyUrl` to <ScaleMuleProvider>. See @scalemule/nextjs README \u2192 Proxy Mode.'
+      );
+    }
+  }, [apiKey, analyticsProxyUrl, publishableKey]);
   const [loading, setLoading] = React.useState(false);
   const [error, setError] = React.useState(null);
   const [utmParams, setUtmParams] = React.useState(null);

package/dist/index.mjs

@@ -8904,13 +8904,14 @@ function ScaleMuleProvider({
       analyticsProxyUrl,
       authProxyUrl,
       publishableKey,
+      apiKey,
       gatewayUrl: resolvedGatewayUrl,
       environment: environment || void 0,
       enableAccountSwitcher,
       accountSwitcherPrivacy,
       bootstrapFlags
     }),
-    [client, money, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, effectiveMediaPolicy]
+    [client, money, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, apiKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, effectiveMediaPolicy]
   );
   return /* @__PURE__ */ jsx(ScaleMuleContext.Provider, { value, children });
 }
@@ -11625,7 +11626,18 @@ function useAnalytics(options = {}) {
     eventDedupMs = DEFAULT_EVENT_DEDUP_MS
   } = options;
   const shouldAutoCaptureUtmParams = autoCaptureUtmParams ?? autoCapturUtmParams ?? true;
-  const { client, user, analyticsProxyUrl, publishableKey, gatewayUrl } = useScaleMule();
+  const { client, user, analyticsProxyUrl, publishableKey, apiKey, gatewayUrl } = useScaleMule();
+  const proxyModeMisconfigWarnedRef = useRef(false);
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    if (proxyModeMisconfigWarnedRef.current) return;
+    if (apiKey === "proxy-mode" && !analyticsProxyUrl && !publishableKey) {
+      proxyModeMisconfigWarnedRef.current = true;
+      console.warn(
+        '[ScaleMule] useAnalytics: apiKey="proxy-mode" but neither `analyticsProxyUrl` nor `publishableKey` is configured. Every trackEvent / trackPageView will silently 401 against the gateway. Add an analytics proxy route (createAnalyticsRoutes({ simpleProxy: true })) and pass `analyticsProxyUrl` to <ScaleMuleProvider>. See @scalemule/nextjs README \u2192 Proxy Mode.'
+      );
+    }
+  }, [apiKey, analyticsProxyUrl, publishableKey]);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState(null);
   const [utmParams, setUtmParams] = useState(null);

package/package.json

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