@scalemule/nextjs 0.1.30 → 0.1.32

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

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, AudioService, TtsService, TtsJobStatus, TtsAudioInfo, FileStatus } from '@scalemule/sdk';
+import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, AudioService, TtsService, SocialService, SocialPolicyService, TtsJobStatus, TtsAudioInfo, FileStatus } from '@scalemule/sdk';
 import * as React from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
@@ -223,6 +223,10 @@ interface ScaleMuleContextValue {
     media: unknown;
     /** Base SDK TTS service — exposed for `useTtsJob()` and direct narration requests */
     tts: TtsService;
+    /** Base SDK social graph service — follow graph, posts, feed, likes, and activity */
+    social: SocialService;
+    /** Base SDK social policy service — privacy decisions, requests, blocks, reports */
+    socialPolicy: SocialPolicyService;
     /**
      * Default media policy for `useMedia()` calls. Set via
      * `<ScaleMuleProvider mediaPolicy="…">`; per-call overrides win.
@@ -245,6 +249,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

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, AudioService, TtsService, TtsJobStatus, TtsAudioInfo, FileStatus } from '@scalemule/sdk';
+import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, AudioService, TtsService, SocialService, SocialPolicyService, TtsJobStatus, TtsAudioInfo, FileStatus } from '@scalemule/sdk';
 import * as React from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
@@ -223,6 +223,10 @@ interface ScaleMuleContextValue {
     media: unknown;
     /** Base SDK TTS service — exposed for `useTtsJob()` and direct narration requests */
     tts: TtsService;
+    /** Base SDK social graph service — follow graph, posts, feed, likes, and activity */
+    social: SocialService;
+    /** Base SDK social policy service — privacy decisions, requests, blocks, reports */
+    socialPolicy: SocialPolicyService;
     /**
      * Default media policy for `useMedia()` calls. Set via
      * `<ScaleMuleProvider mediaPolicy="…">`; per-call overrides win.
@@ -245,6 +249,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

@@ -4496,6 +4496,116 @@ var SocialService = class extends ServiceModule {
     return this.comment(postId, data);
   }
 };
+var SocialPolicyService = class extends ServiceModule {
+  constructor() {
+    super(...arguments);
+    this.basePath = "/v1/social-policy";
+  }
+  decide(request, options) {
+    return this.post("/decision", withDefaultContext(request), options);
+  }
+  batchDecide(request, options) {
+    return this.post("/decisions/batch", request, options);
+  }
+  decideAction(action, actor, target, options) {
+    return this.decide(
+      {
+        app_key: options?.appKey,
+        account_id: options?.accountId,
+        policy_pack: options?.policyPack,
+        actor,
+        target,
+        action,
+        context: options?.context,
+        metadata: options?.metadata
+      },
+      options?.requestOptions
+    );
+  }
+  decideFollow(actor, target, options) {
+    return this.decideAction("follow", actor, target, options);
+  }
+  decideDirectMessage(actor, target, options) {
+    return this.decideAction("message_direct", actor, target, options);
+  }
+  decideContactRequest(actor, target, options) {
+    return this.decideAction("connect_request", actor, target, options);
+  }
+  getSettings(identityId, options) {
+    return this._get(`/settings/${identityId}`, options);
+  }
+  updateSettings(identityId, request, options) {
+    return this.patch(`/settings/${identityId}`, request, options);
+  }
+  createRelationship(request, options) {
+    return this.post("/relationships", request, options);
+  }
+  listRelationships(params, options) {
+    return this._get(this.withQuery("/relationships", toQueryParams(params)), options);
+  }
+  deleteRelationship(relationshipId, options) {
+    return this.del(`/relationships/${relationshipId}`, options);
+  }
+  createContactRequest(request, options) {
+    return this.post("/contact-requests", request, options);
+  }
+  listContactRequestInbox(params, options) {
+    return this._get(
+      this.withQuery("/contact-requests/inbox", toQueryParams(params)),
+      options
+    );
+  }
+  listContactRequestSent(params, options) {
+    return this._get(
+      this.withQuery("/contact-requests/sent", toQueryParams(params)),
+      options
+    );
+  }
+  acceptContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/accept`, void 0, options);
+  }
+  ignoreContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/ignore`, void 0, options);
+  }
+  declineContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/decline`, void 0, options);
+  }
+  reportContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/report`, void 0, options);
+  }
+  block(request, options) {
+    return this.post("/block", request, options);
+  }
+  unblock(request, options) {
+    return this.post("/unblock", request, options);
+  }
+  mute(request, options) {
+    return this.post("/mute", request, options);
+  }
+  unmute(request, options) {
+    return this.post("/unmute", request, options);
+  }
+  report(request, options) {
+    return this.post("/report", request, options);
+  }
+  listPolicyPacks(options) {
+    return this._get("/policy-packs", options);
+  }
+};
+function withDefaultContext(request) {
+  return {
+    ...request,
+    context: request.context ?? {}
+  };
+}
+function toQueryParams(params) {
+  if (!params) return void 0;
+  const query = {};
+  for (const [key, value] of Object.entries(params)) {
+    query[key] = value;
+  }
+  return query;
+}
 var ReferralsService = class extends ServiceModule {
   constructor() {
     super(...arguments);
@@ -7543,6 +7653,7 @@ var ScaleMule = class {
     this.chat = new ChatService(this._client);
     this.conference = new ConferenceService(this._client);
     this.social = new SocialService(this._client);
+    this.socialPolicy = new SocialPolicyService(this._client);
     this.referrals = new ReferralsService(this._client);
     this.billing = new BillingService(this._client);
     this.analytics = new AnalyticsService(this._client);
@@ -8915,6 +9026,8 @@ function ScaleMuleProvider({
       audio: baseClient.audio,
       media: baseClient.media,
       tts: baseClient.tts,
+      social: baseClient.social,
+      socialPolicy: baseClient.socialPolicy,
       mediaPolicy: effectiveMediaPolicy,
       user,
       setUser: handleSetUser,
@@ -8924,13 +9037,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 +11759,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

@@ -4476,6 +4476,116 @@ var SocialService = class extends ServiceModule {
     return this.comment(postId, data);
   }
 };
+var SocialPolicyService = class extends ServiceModule {
+  constructor() {
+    super(...arguments);
+    this.basePath = "/v1/social-policy";
+  }
+  decide(request, options) {
+    return this.post("/decision", withDefaultContext(request), options);
+  }
+  batchDecide(request, options) {
+    return this.post("/decisions/batch", request, options);
+  }
+  decideAction(action, actor, target, options) {
+    return this.decide(
+      {
+        app_key: options?.appKey,
+        account_id: options?.accountId,
+        policy_pack: options?.policyPack,
+        actor,
+        target,
+        action,
+        context: options?.context,
+        metadata: options?.metadata
+      },
+      options?.requestOptions
+    );
+  }
+  decideFollow(actor, target, options) {
+    return this.decideAction("follow", actor, target, options);
+  }
+  decideDirectMessage(actor, target, options) {
+    return this.decideAction("message_direct", actor, target, options);
+  }
+  decideContactRequest(actor, target, options) {
+    return this.decideAction("connect_request", actor, target, options);
+  }
+  getSettings(identityId, options) {
+    return this._get(`/settings/${identityId}`, options);
+  }
+  updateSettings(identityId, request, options) {
+    return this.patch(`/settings/${identityId}`, request, options);
+  }
+  createRelationship(request, options) {
+    return this.post("/relationships", request, options);
+  }
+  listRelationships(params, options) {
+    return this._get(this.withQuery("/relationships", toQueryParams(params)), options);
+  }
+  deleteRelationship(relationshipId, options) {
+    return this.del(`/relationships/${relationshipId}`, options);
+  }
+  createContactRequest(request, options) {
+    return this.post("/contact-requests", request, options);
+  }
+  listContactRequestInbox(params, options) {
+    return this._get(
+      this.withQuery("/contact-requests/inbox", toQueryParams(params)),
+      options
+    );
+  }
+  listContactRequestSent(params, options) {
+    return this._get(
+      this.withQuery("/contact-requests/sent", toQueryParams(params)),
+      options
+    );
+  }
+  acceptContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/accept`, void 0, options);
+  }
+  ignoreContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/ignore`, void 0, options);
+  }
+  declineContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/decline`, void 0, options);
+  }
+  reportContactRequest(requestId, options) {
+    return this.post(`/contact-requests/${requestId}/report`, void 0, options);
+  }
+  block(request, options) {
+    return this.post("/block", request, options);
+  }
+  unblock(request, options) {
+    return this.post("/unblock", request, options);
+  }
+  mute(request, options) {
+    return this.post("/mute", request, options);
+  }
+  unmute(request, options) {
+    return this.post("/unmute", request, options);
+  }
+  report(request, options) {
+    return this.post("/report", request, options);
+  }
+  listPolicyPacks(options) {
+    return this._get("/policy-packs", options);
+  }
+};
+function withDefaultContext(request) {
+  return {
+    ...request,
+    context: request.context ?? {}
+  };
+}
+function toQueryParams(params) {
+  if (!params) return void 0;
+  const query = {};
+  for (const [key, value] of Object.entries(params)) {
+    query[key] = value;
+  }
+  return query;
+}
 var ReferralsService = class extends ServiceModule {
   constructor() {
     super(...arguments);
@@ -7523,6 +7633,7 @@ var ScaleMule = class {
     this.chat = new ChatService(this._client);
     this.conference = new ConferenceService(this._client);
     this.social = new SocialService(this._client);
+    this.socialPolicy = new SocialPolicyService(this._client);
     this.referrals = new ReferralsService(this._client);
     this.billing = new BillingService(this._client);
     this.analytics = new AnalyticsService(this._client);
@@ -8895,6 +9006,8 @@ function ScaleMuleProvider({
       audio: baseClient.audio,
       media: baseClient.media,
       tts: baseClient.tts,
+      social: baseClient.social,
+      socialPolicy: baseClient.socialPolicy,
       mediaPolicy: effectiveMediaPolicy,
       user,
       setUser: handleSetUser,
@@ -8904,13 +9017,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 +11739,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);