@scalemule/nextjs 0.1.8 → 0.1.10

package/README.md

@@ -132,7 +132,67 @@ function LoginPage() {
 }
 ```
 
-### `useContent()`
+### `useMedia()` — recommended for image / video / audio uploads
+
+One hook covers every MIME type, defaults to private, and auto-routes images
+through the photo pipeline (optimization, transform breakpoints) and videos
+through the video pipeline (HLS transcoding). Drop the result `file_id` into
+a chat message or render it with `<ScaleMuleMedia />` and progressive
+enhancement just works.
+
+```tsx
+import { useMedia, ScaleMuleMedia } from '@scalemule/nextjs'
+
+function Composer({ conversationId }: { conversationId: string }) {
+  const { upload, uploading } = useMedia()
+
+  async function handleFile(file: File) {
+    const result = await upload(file)
+    // result.file_id is private by default; post the message with it.
+    await postMessage({ conversationId, attachments: [{ file_id: result.file_id }] })
+  }
+
+  return <input type="file" disabled={uploading} onChange={(e) => handleFile(e.target.files![0])} />
+}
+
+function Attachment({ fileId, conversationId, mimeType }: {
+  fileId: string; conversationId: string; mimeType: string
+}) {
+  // <ScaleMuleMedia /> uses useFileStatus internally; with conversationId
+  // it subscribes to the conversation channel for live optimize/transcode
+  // updates instead of polling.
+  return (
+    <ScaleMuleMedia
+      fileId={fileId}
+      mimeType={mimeType}
+      conversationId={conversationId}
+    />
+  )
+}
+```
+
+See [`docs/MEDIA-UPLOADS.md`](https://github.com/scalemule/scalemule-repos/blob/main/docs/MEDIA-UPLOADS.md)
+for the full decision tree (which hook for which app, fast/safe policy modes,
+private vs public visibility, anti-patterns).
+
+### `useFileStatus()` — read-side progressive enhancement
+
+```tsx
+import { useFileStatus } from '@scalemule/nextjs'
+
+// Chat surface — subscribe to the conversation channel for push updates.
+const { status, isReady } = useFileStatus({ fileId, conversationId })
+
+// Non-chat — pull-only with optional polling.
+const { status, isReady } = useFileStatus({ fileId, pollIntervalMs: 2000 })
+```
+
+### `useContent()` — generic file uploads (legacy)
+
+> **Deprecated for chat / progressive media.** Use `useMedia()` instead.
+> `useContent()` remains available for plain non-image/video file lists
+> (documents, downloads). It does not auto-route through the photo/video
+> pipelines and does not enforce private-by-default for chat surfaces.
 
 ```tsx
 import { useContent } from '@scalemule/nextjs'

package/dist/index.d.mts

@@ -216,13 +216,13 @@ interface ScaleMuleProviderProps extends ScaleMuleConfig {
      *
      * The platform stores the per-app policy in
      * `application_storage_settings.media_policy` (Phase 4 / P3, live in
-     * prod). That endpoint is `MemberOnly` admin-auth, so end-user-context
-     * provider can't fetch it directly — apps that want policy-driven
-     * defaults should declare the value here, mirroring whatever the
-     * platform admin set.
+     * prod). On boot, the provider fetches `GET /v1/storage/policy` (a
+     * lightweight `EndUserOnly` endpoint added in `@scalemule/sdk@0.0.45`)
+     * and uses the returned policy as the effective default.
      *
-     * Default: undefined → `useMedia()` falls back to its built-in
-     * `safe_visible` default.
+     * Passing this prop overrides the auto-fetched value — useful for
+     * tests or when an app needs to force a specific mode regardless of
+     * platform config.
      */
     mediaPolicy?: MediaPolicy;
 }
@@ -324,25 +324,39 @@ interface UseContentOptions {
  */
 declare function useContent(options?: UseContentOptions): UseContentReturn;
 
+/**
+ * Conversation kinds recognized by the chat realtime channel naming scheme.
+ * Matches `broadcast_to_conversation` in `ms/scalemule-chat/src/realtime.rs`.
+ */
+type ConversationKind = 'standard' | 'large_room' | 'broadcast' | 'support';
 interface UseFileStatusOptions {
     /** Storage file_id to read status for. */
     fileId: string | null | undefined;
     /**
      * Optional poll interval in milliseconds. If set, the hook re-fetches
-     * status every `pollIntervalMs`. Useful while waiting for transcode /
-     * optimization to complete. Pass `null` (default) for a one-shot read.
-     *
-     * Polling stops automatically once `scan.status === 'clean'` AND the
-     * caller's expected pipeline is done (`urls.optimized` returns 200 for
-     * images, `urls.hls` returns 200 for videos). Today the hook can only
-     * detect scan clean — broader pipeline-done detection lands when Phase 3
-     * enriches the optimize/transcode response fields.
+     * status every `pollIntervalMs` until scan goes clean. Useful for
+     * non-chat surfaces or as a fallback alongside `conversationId` push.
      */
     pollIntervalMs?: number | null;
+    /** Disable the hook (don't fetch). Useful when `fileId` is conditional. */
+    disabled?: boolean;
     /**
-     * Disable the hook (don't fetch). Useful when `fileId` is conditional.
+     * Chat-surface push variant: subscribe to the conversation's realtime
+     * channel and refresh when a `file_status_changed` event arrives for
+     * `fileId`. Auth rides the existing per-conversation channel ACL.
      */
-    disabled?: boolean;
+    conversationId?: string | null;
+    /**
+     * Conversation kind, controls the channel name prefix:
+     *   - `standard` (default) → `conversation:{id}`
+     *   - `large_room` → `conversation:lr:{id}`
+     *   - `broadcast` → `conversation:bc:{id}`
+     *   - `support` → `conversation:support:{id}`
+     *
+     * If you only have a `messageId`, look up the conversation first via
+     * `client.chat.getMessage(messageId)` and pass the result here.
+     */
+    conversationKind?: ConversationKind;
 }
 interface UseFileStatusReturn {
     /** The latest status response, or null on first render / disabled. */
@@ -362,29 +376,39 @@ interface UseFileStatusReturn {
     refresh: () => Promise<void>;
 }
 /**
- * Subscribes to {@link FileStatus} for a single file. Today this is a
- * pull-only hook — single fetch by default, optional polling.
+ * Subscribes to {@link FileStatus} for a single file.
  *
- * Phase 3 of the realtime-chat media pipeline ADR will add a push variant
- * for chat surfaces — `useFileStatus({ messageId })` will subscribe to
- * `file.status` events on the existing per-conversation realtime channel
- * via the `scalemule-chat` translation bridge (P5'). Until that lands,
- * customers using this hook from chat surfaces should pass `pollIntervalMs`
- * in the 1–3 second range while a media pipeline is expected to be running,
- * then drop the polling once `isReady` is true.
+ * Three call shapes:
  *
- * @example
+ * 1. **Pull-only** — `useFileStatus({ fileId })` plus optional `pollIntervalMs`.
+ *    One-shot fetch; useful for non-chat surfaces or static reads.
+ *
+ * 2. **Chat-surface push** — `useFileStatus({ fileId, conversationId, conversationKind? })`.
+ *    Subscribes to the conversation channel and refreshes when
+ *    `file_status_changed` arrives for this `fileId`. The chat service's
+ *    media-status bridge fans photo/video lifecycle events into the per-conversation
+ *    channel; the hook drops events for other files and dedupes against polling.
+ *
+ * 3. **Push + slow poll fallback** — combine `conversationId` with `pollIntervalMs`
+ *    if you want belt-and-suspenders for environments where the websocket may drop.
+ *
+ * The `surface: 'profile'` push variant (private-user channel) is deferred until
+ * the realtime SDK exposes private-channel subscription by user.
+ *
+ * @example Chat surface (push)
  * ```tsx
- * function ChatImage({ fileId }: { fileId: string }) {
- *   const { status, isReady } = useFileStatus({
- *     fileId,
- *     pollIntervalMs: 2000,
- *   });
+ * function ChatImage({ fileId, conversationId }: { fileId: string; conversationId: string }) {
+ *   const { status, isReady } = useFileStatus({ fileId, conversationId });
  *   if (!isReady) return <div>Scanning…</div>;
  *   const src = status?.urls.optimized ?? status?.urls.original;
  *   return <img src={src} />;
  * }
  * ```
+ *
+ * @example Non-chat surface (pull + poll)
+ * ```tsx
+ * const { status, isReady } = useFileStatus({ fileId, pollIntervalMs: 2000 });
+ * ```
  */
 declare function useFileStatus(options: UseFileStatusOptions): UseFileStatusReturn;
 
@@ -413,9 +437,23 @@ interface ScaleMuleMediaProps {
     /**
      * Polling interval while waiting for the media pipeline to complete.
      * Defaults to 2000ms; set to `null` to disable polling. Polling stops
-     * automatically once scan is clean.
+     * automatically once scan is clean. When `conversationId` is set the
+     * component receives push updates and you can usually pass `null`.
      */
     pollIntervalMs?: number | null;
+    /**
+     * Chat-surface push: when set, the underlying `useFileStatus` hook
+     * subscribes to the conversation's realtime channel and refreshes on
+     * `file_status_changed` events for this `fileId`. See `useFileStatus`
+     * docs for channel naming and bridge behaviour.
+     */
+    conversationId?: string | null;
+    /**
+     * Conversation kind, controls the channel name prefix
+     * (`conversation:{id}` vs `conversation:lr|bc|support:{id}`).
+     * Default is `'standard'`.
+     */
+    conversationKind?: ConversationKind;
     /**
      * Render a custom placeholder while waiting for scan / upload. Defaults
      * to a tiny "Loading…" div. Receives the current FileStatus (or null).
@@ -950,4 +988,4 @@ declare function createSafeLogger(prefix: string): {
     error: (message: string, data?: unknown) => void;
 };
 
-export { ApiError$1 as ApiError, type FeatureFlagEvaluation, type FeatureFlagEvaluation as FeatureFlagResult, type FeedbackItem, type FeedbackItemInput, type FeedbackPriority, type FeedbackStatus, type FeedbackType, FeedbackWidget, type FeedbackWidgetConfig, type FeedbackWidgetProps, ListFilesParams, LoginResponse, type MediaPolicy, type MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, ScaleMuleMedia, type ScaleMuleMediaProps, ScaleMuleProvider, type ScaleMuleProviderProps, UseAnalyticsOptions, UseAnalyticsReturn, UseAuthReturn, UseBillingReturn, UseContentReturn, type UseFeatureFlagsOptions, type UseFeatureFlagsReturn, type UseFeedbackOptions, type UseFeedbackResult, type UseFileStatusOptions, type UseFileStatusReturn, type UseFeatureFlagsOptions as UseFlagsOptions, type UseFeatureFlagsReturn as UseFlagsReturn, type UseMediaReturn, type UseMediaUploadOptions, type UsePushNotificationsOptions, type UsePushNotificationsReturn, type UseRealtimeOptions, type UseRealtimeReturn, type UseShareOptions, type UseShareReturn, UseUserReturn, User, type UsernameValidationResult, composePhone, createSafeLogger, normalizePhone, phoneCountries, sanitizeForLog, useAnalytics, useAuth, useBilling, useContent, useFeatureFlags, useFeedback, useFileStatus, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };
+export { ApiError$1 as ApiError, type ConversationKind, type FeatureFlagEvaluation, type FeatureFlagEvaluation as FeatureFlagResult, type FeedbackItem, type FeedbackItemInput, type FeedbackPriority, type FeedbackStatus, type FeedbackType, FeedbackWidget, type FeedbackWidgetConfig, type FeedbackWidgetProps, ListFilesParams, LoginResponse, type MediaPolicy, type MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, ScaleMuleMedia, type ScaleMuleMediaProps, ScaleMuleProvider, type ScaleMuleProviderProps, UseAnalyticsOptions, UseAnalyticsReturn, UseAuthReturn, UseBillingReturn, UseContentReturn, type UseFeatureFlagsOptions, type UseFeatureFlagsReturn, type UseFeedbackOptions, type UseFeedbackResult, type UseFileStatusOptions, type UseFileStatusReturn, type UseFeatureFlagsOptions as UseFlagsOptions, type UseFeatureFlagsReturn as UseFlagsReturn, type UseMediaReturn, type UseMediaUploadOptions, type UsePushNotificationsOptions, type UsePushNotificationsReturn, type UseRealtimeOptions, type UseRealtimeReturn, type UseShareOptions, type UseShareReturn, UseUserReturn, User, type UsernameValidationResult, composePhone, createSafeLogger, normalizePhone, phoneCountries, sanitizeForLog, useAnalytics, useAuth, useBilling, useContent, useFeatureFlags, useFeedback, useFileStatus, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };

package/dist/index.d.ts

@@ -216,13 +216,13 @@ interface ScaleMuleProviderProps extends ScaleMuleConfig {
      *
      * The platform stores the per-app policy in
      * `application_storage_settings.media_policy` (Phase 4 / P3, live in
-     * prod). That endpoint is `MemberOnly` admin-auth, so end-user-context
-     * provider can't fetch it directly — apps that want policy-driven
-     * defaults should declare the value here, mirroring whatever the
-     * platform admin set.
+     * prod). On boot, the provider fetches `GET /v1/storage/policy` (a
+     * lightweight `EndUserOnly` endpoint added in `@scalemule/sdk@0.0.45`)
+     * and uses the returned policy as the effective default.
      *
-     * Default: undefined → `useMedia()` falls back to its built-in
-     * `safe_visible` default.
+     * Passing this prop overrides the auto-fetched value — useful for
+     * tests or when an app needs to force a specific mode regardless of
+     * platform config.
      */
     mediaPolicy?: MediaPolicy;
 }
@@ -324,25 +324,39 @@ interface UseContentOptions {
  */
 declare function useContent(options?: UseContentOptions): UseContentReturn;
 
+/**
+ * Conversation kinds recognized by the chat realtime channel naming scheme.
+ * Matches `broadcast_to_conversation` in `ms/scalemule-chat/src/realtime.rs`.
+ */
+type ConversationKind = 'standard' | 'large_room' | 'broadcast' | 'support';
 interface UseFileStatusOptions {
     /** Storage file_id to read status for. */
     fileId: string | null | undefined;
     /**
      * Optional poll interval in milliseconds. If set, the hook re-fetches
-     * status every `pollIntervalMs`. Useful while waiting for transcode /
-     * optimization to complete. Pass `null` (default) for a one-shot read.
-     *
-     * Polling stops automatically once `scan.status === 'clean'` AND the
-     * caller's expected pipeline is done (`urls.optimized` returns 200 for
-     * images, `urls.hls` returns 200 for videos). Today the hook can only
-     * detect scan clean — broader pipeline-done detection lands when Phase 3
-     * enriches the optimize/transcode response fields.
+     * status every `pollIntervalMs` until scan goes clean. Useful for
+     * non-chat surfaces or as a fallback alongside `conversationId` push.
      */
     pollIntervalMs?: number | null;
+    /** Disable the hook (don't fetch). Useful when `fileId` is conditional. */
+    disabled?: boolean;
     /**
-     * Disable the hook (don't fetch). Useful when `fileId` is conditional.
+     * Chat-surface push variant: subscribe to the conversation's realtime
+     * channel and refresh when a `file_status_changed` event arrives for
+     * `fileId`. Auth rides the existing per-conversation channel ACL.
      */
-    disabled?: boolean;
+    conversationId?: string | null;
+    /**
+     * Conversation kind, controls the channel name prefix:
+     *   - `standard` (default) → `conversation:{id}`
+     *   - `large_room` → `conversation:lr:{id}`
+     *   - `broadcast` → `conversation:bc:{id}`
+     *   - `support` → `conversation:support:{id}`
+     *
+     * If you only have a `messageId`, look up the conversation first via
+     * `client.chat.getMessage(messageId)` and pass the result here.
+     */
+    conversationKind?: ConversationKind;
 }
 interface UseFileStatusReturn {
     /** The latest status response, or null on first render / disabled. */
@@ -362,29 +376,39 @@ interface UseFileStatusReturn {
     refresh: () => Promise<void>;
 }
 /**
- * Subscribes to {@link FileStatus} for a single file. Today this is a
- * pull-only hook — single fetch by default, optional polling.
+ * Subscribes to {@link FileStatus} for a single file.
  *
- * Phase 3 of the realtime-chat media pipeline ADR will add a push variant
- * for chat surfaces — `useFileStatus({ messageId })` will subscribe to
- * `file.status` events on the existing per-conversation realtime channel
- * via the `scalemule-chat` translation bridge (P5'). Until that lands,
- * customers using this hook from chat surfaces should pass `pollIntervalMs`
- * in the 1–3 second range while a media pipeline is expected to be running,
- * then drop the polling once `isReady` is true.
+ * Three call shapes:
  *
- * @example
+ * 1. **Pull-only** — `useFileStatus({ fileId })` plus optional `pollIntervalMs`.
+ *    One-shot fetch; useful for non-chat surfaces or static reads.
+ *
+ * 2. **Chat-surface push** — `useFileStatus({ fileId, conversationId, conversationKind? })`.
+ *    Subscribes to the conversation channel and refreshes when
+ *    `file_status_changed` arrives for this `fileId`. The chat service's
+ *    media-status bridge fans photo/video lifecycle events into the per-conversation
+ *    channel; the hook drops events for other files and dedupes against polling.
+ *
+ * 3. **Push + slow poll fallback** — combine `conversationId` with `pollIntervalMs`
+ *    if you want belt-and-suspenders for environments where the websocket may drop.
+ *
+ * The `surface: 'profile'` push variant (private-user channel) is deferred until
+ * the realtime SDK exposes private-channel subscription by user.
+ *
+ * @example Chat surface (push)
  * ```tsx
- * function ChatImage({ fileId }: { fileId: string }) {
- *   const { status, isReady } = useFileStatus({
- *     fileId,
- *     pollIntervalMs: 2000,
- *   });
+ * function ChatImage({ fileId, conversationId }: { fileId: string; conversationId: string }) {
+ *   const { status, isReady } = useFileStatus({ fileId, conversationId });
  *   if (!isReady) return <div>Scanning…</div>;
  *   const src = status?.urls.optimized ?? status?.urls.original;
  *   return <img src={src} />;
  * }
  * ```
+ *
+ * @example Non-chat surface (pull + poll)
+ * ```tsx
+ * const { status, isReady } = useFileStatus({ fileId, pollIntervalMs: 2000 });
+ * ```
  */
 declare function useFileStatus(options: UseFileStatusOptions): UseFileStatusReturn;
 
@@ -413,9 +437,23 @@ interface ScaleMuleMediaProps {
     /**
      * Polling interval while waiting for the media pipeline to complete.
      * Defaults to 2000ms; set to `null` to disable polling. Polling stops
-     * automatically once scan is clean.
+     * automatically once scan is clean. When `conversationId` is set the
+     * component receives push updates and you can usually pass `null`.
      */
     pollIntervalMs?: number | null;
+    /**
+     * Chat-surface push: when set, the underlying `useFileStatus` hook
+     * subscribes to the conversation's realtime channel and refreshes on
+     * `file_status_changed` events for this `fileId`. See `useFileStatus`
+     * docs for channel naming and bridge behaviour.
+     */
+    conversationId?: string | null;
+    /**
+     * Conversation kind, controls the channel name prefix
+     * (`conversation:{id}` vs `conversation:lr|bc|support:{id}`).
+     * Default is `'standard'`.
+     */
+    conversationKind?: ConversationKind;
     /**
      * Render a custom placeholder while waiting for scan / upload. Defaults
      * to a tiny "Loading…" div. Receives the current FileStatus (or null).
@@ -950,4 +988,4 @@ declare function createSafeLogger(prefix: string): {
     error: (message: string, data?: unknown) => void;
 };
 
-export { ApiError$1 as ApiError, type FeatureFlagEvaluation, type FeatureFlagEvaluation as FeatureFlagResult, type FeedbackItem, type FeedbackItemInput, type FeedbackPriority, type FeedbackStatus, type FeedbackType, FeedbackWidget, type FeedbackWidgetConfig, type FeedbackWidgetProps, ListFilesParams, LoginResponse, type MediaPolicy, type MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, ScaleMuleMedia, type ScaleMuleMediaProps, ScaleMuleProvider, type ScaleMuleProviderProps, UseAnalyticsOptions, UseAnalyticsReturn, UseAuthReturn, UseBillingReturn, UseContentReturn, type UseFeatureFlagsOptions, type UseFeatureFlagsReturn, type UseFeedbackOptions, type UseFeedbackResult, type UseFileStatusOptions, type UseFileStatusReturn, type UseFeatureFlagsOptions as UseFlagsOptions, type UseFeatureFlagsReturn as UseFlagsReturn, type UseMediaReturn, type UseMediaUploadOptions, type UsePushNotificationsOptions, type UsePushNotificationsReturn, type UseRealtimeOptions, type UseRealtimeReturn, type UseShareOptions, type UseShareReturn, UseUserReturn, User, type UsernameValidationResult, composePhone, createSafeLogger, normalizePhone, phoneCountries, sanitizeForLog, useAnalytics, useAuth, useBilling, useContent, useFeatureFlags, useFeedback, useFileStatus, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };
+export { ApiError$1 as ApiError, type ConversationKind, type FeatureFlagEvaluation, type FeatureFlagEvaluation as FeatureFlagResult, type FeedbackItem, type FeedbackItemInput, type FeedbackPriority, type FeedbackStatus, type FeedbackType, FeedbackWidget, type FeedbackWidgetConfig, type FeedbackWidgetProps, ListFilesParams, LoginResponse, type MediaPolicy, type MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, ScaleMuleMedia, type ScaleMuleMediaProps, ScaleMuleProvider, type ScaleMuleProviderProps, UseAnalyticsOptions, UseAnalyticsReturn, UseAuthReturn, UseBillingReturn, UseContentReturn, type UseFeatureFlagsOptions, type UseFeatureFlagsReturn, type UseFeedbackOptions, type UseFeedbackResult, type UseFileStatusOptions, type UseFileStatusReturn, type UseFeatureFlagsOptions as UseFlagsOptions, type UseFeatureFlagsReturn as UseFlagsReturn, type UseMediaReturn, type UseMediaUploadOptions, type UsePushNotificationsOptions, type UsePushNotificationsReturn, type UseRealtimeOptions, type UseRealtimeReturn, type UseShareOptions, type UseShareReturn, UseUserReturn, User, type UsernameValidationResult, composePhone, createSafeLogger, normalizePhone, phoneCountries, sanitizeForLog, useAnalytics, useAuth, useBilling, useContent, useFeatureFlags, useFeedback, useFileStatus, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };

package/dist/index.js

@@ -7569,6 +7569,28 @@ function ScaleMuleProvider({
       debug
     });
   }, [apiKey, applicationId, environment, resolvedGatewayUrl, debug]);
+  const [fetchedPolicy, setFetchedPolicy] = React.useState(void 0);
+  React.useEffect(() => {
+    if (mediaPolicy) return;
+    let mounted = true;
+    void (async () => {
+      try {
+        const fn = baseClient.storage.getPolicy;
+        if (typeof fn !== "function") return;
+        const r = await fn.call(baseClient.storage);
+        if (!mounted) return;
+        const v = r?.data?.media_policy;
+        if (v === "fast_trusted" || v === "safe_visible" || v === "safe_public" || v === "moderated" || v === "compliance") {
+          setFetchedPolicy(v);
+        }
+      } catch {
+      }
+    })();
+    return () => {
+      mounted = false;
+    };
+  }, [baseClient, mediaPolicy]);
+  const effectiveMediaPolicy = mediaPolicy ?? fetchedPolicy;
   React.useEffect(() => {
     const token = client.getSessionToken();
     if (token) {
@@ -7672,7 +7694,7 @@ function ScaleMuleProvider({
       photo: baseClient.photo,
       video: baseClient.video,
       audio: baseClient.audio,
-      mediaPolicy,
+      mediaPolicy: effectiveMediaPolicy,
       user,
       setUser: handleSetUser,
       initializing,
@@ -7687,7 +7709,7 @@ function ScaleMuleProvider({
       accountSwitcherPrivacy,
       bootstrapFlags
     }),
-    [client, money$1, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, mediaPolicy]
+    [client, money$1, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, effectiveMediaPolicy]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(ScaleMuleContext.Provider, { value, children });
 }
@@ -9103,10 +9125,13 @@ function useMedia() {
     async (fileId) => {
       setError(null);
       try {
-        const r = await storage.delete(fileId);
-        if (r.error) {
-          if (r.error.status === 404) return;
-          throw r.error;
+        const [, storageResult] = await Promise.all([
+          photo.delete(fileId).catch(() => void 0),
+          storage.delete(fileId)
+        ]);
+        if (storageResult.error) {
+          if (storageResult.error.status === 404) return;
+          throw storageResult.error;
         }
       } catch (err) {
         const e = err;
@@ -9114,13 +9139,32 @@ function useMedia() {
         throw e;
       }
     },
-    [storage]
+    [storage, photo]
   );
   return { upload, cancelUpload, error, uploading };
 }
+function conversationChannel(kind, id) {
+  switch (kind) {
+    case "large_room":
+      return `conversation:lr:${id}`;
+    case "broadcast":
+      return `conversation:bc:${id}`;
+    case "support":
+      return `conversation:support:${id}`;
+    case "standard":
+    default:
+      return `conversation:${id}`;
+  }
+}
 function useFileStatus(options) {
-  const { storage } = useScaleMule();
-  const { fileId, pollIntervalMs = null, disabled = false } = options;
+  const { storage, realtime } = useScaleMule();
+  const {
+    fileId,
+    pollIntervalMs = null,
+    disabled = false,
+    conversationId = null,
+    conversationKind = "standard"
+  } = options;
   const [status, setStatus] = React.useState(null);
   const [loading, setLoading] = React.useState(false);
   const [error, setError] = React.useState(null);
@@ -9152,13 +9196,40 @@ function useFileStatus(options) {
   }, [fetchStatus]);
   React.useEffect(() => {
     if (!pollIntervalMs || disabled || !fileId) return;
-    const isClean = status?.scan.status === "clean";
-    if (isClean) return;
+    const scan = status?.scan.status;
+    if (scan === "threat" || scan === "quarantined" || scan === "error") return;
+    const optimizePending = status?.optimize != null && status.optimize.status !== "done";
+    const transcodePending = status?.transcode != null && status.transcode.status !== "done";
+    const pipelinePending = optimizePending || transcodePending;
+    const isSettled = scan === "clean" && !pipelinePending;
+    if (isSettled) return;
     const id = setInterval(() => {
       void fetchStatus();
     }, pollIntervalMs);
     return () => clearInterval(id);
-  }, [pollIntervalMs, disabled, fileId, status?.scan.status, fetchStatus]);
+  }, [
+    pollIntervalMs,
+    disabled,
+    fileId,
+    status?.scan.status,
+    status?.optimize,
+    status?.transcode,
+    fetchStatus
+  ]);
+  React.useEffect(() => {
+    if (!conversationId || !fileId || disabled) return;
+    const channel = conversationChannel(conversationKind, conversationId);
+    const unsub = realtime.subscribe(channel, (data) => {
+      if (typeof data !== "object" || data === null) return;
+      const payload = data;
+      const wrapped = "data" in payload && typeof payload.data === "object" && payload.data !== null ? payload.data : payload;
+      const evt = typeof payload.event === "string" ? payload.event : void 0;
+      if (evt && evt !== "file_status_changed") return;
+      if (wrapped.file_id !== fileId) return;
+      void fetchStatus();
+    });
+    return unsub;
+  }, [realtime, conversationId, conversationKind, fileId, disabled, fetchStatus]);
   const isReady = status?.scan.status === "clean";
   return { status, loading, error, isReady, refresh: fetchStatus };
 }
@@ -9173,32 +9244,54 @@ function ScaleMuleMedia(props) {
     style,
     alt,
     pollIntervalMs = 2e3,
+    conversationId = null,
+    conversationKind,
     renderPlaceholder,
     renderBlocked,
     renderOverride
   } = props;
-  const { status, isReady } = useFileStatus({ fileId, pollIntervalMs });
+  const { gatewayUrl } = useScaleMule();
+  const { status, isReady } = useFileStatus({
+    fileId,
+    pollIntervalMs,
+    conversationId,
+    conversationKind
+  });
+  const absoluteUrl = React__namespace.useCallback(
+    (url) => {
+      if (!url) return null;
+      if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("blob:") || url.startsWith("data:")) {
+        return url;
+      }
+      if (!gatewayUrl) return url;
+      const base = gatewayUrl.endsWith("/") ? gatewayUrl.slice(0, -1) : gatewayUrl;
+      const path = url.startsWith("/") ? url : `/${url}`;
+      return `${base}${path}`;
+    },
+    [gatewayUrl]
+  );
   const isImage = mimeType.startsWith("image/");
   const isVideo = mimeType.startsWith("video/");
   const isAudio = mimeType.startsWith("audio/");
   const src = React.useMemo(() => {
     const scan = status?.scan.status;
     if (scan === "threat" || scan === "quarantined") return null;
-    if (status && isReady) {
-      if (isImage && status.urls.optimized) return status.urls.optimized;
-      if (isVideo && status.urls.hls) return status.urls.hls;
-      return status.urls.original ?? null;
-    }
-    if (blobPreview) return blobPreview;
-    return null;
-  }, [status, isReady, isImage, isVideo, blobPreview]);
+    if (!status) {
+      return blobPreview ?? null;
+    }
+    if (isImage && status.urls.optimized) return absoluteUrl(status.urls.optimized);
+    if (isVideo && status.urls.hls) return absoluteUrl(status.urls.hls);
+    if (status.urls.original) return absoluteUrl(status.urls.original);
+    return blobPreview ?? null;
+  }, [status, isImage, isVideo, blobPreview, absoluteUrl]);
   const renderState = React.useMemo(() => {
     const scan = status?.scan.status;
     if (scan === "threat" || scan === "quarantined") return "blocked";
+    if (status?.urls.original) return "ready";
     if (isReady) return "ready";
     if (blobPreview) return "preview";
     return "pending";
-  }, [status?.scan.status, isReady, blobPreview]);
+  }, [status?.scan.status, status?.urls.original, isReady, blobPreview]);
   const videoRef = React__namespace.useRef(null);
   React.useEffect(() => {
     if (!isVideo) return;

package/dist/index.mjs

@@ -7549,6 +7549,28 @@ function ScaleMuleProvider({
       debug
     });
   }, [apiKey, applicationId, environment, resolvedGatewayUrl, debug]);
+  const [fetchedPolicy, setFetchedPolicy] = useState(void 0);
+  useEffect(() => {
+    if (mediaPolicy) return;
+    let mounted = true;
+    void (async () => {
+      try {
+        const fn = baseClient.storage.getPolicy;
+        if (typeof fn !== "function") return;
+        const r = await fn.call(baseClient.storage);
+        if (!mounted) return;
+        const v = r?.data?.media_policy;
+        if (v === "fast_trusted" || v === "safe_visible" || v === "safe_public" || v === "moderated" || v === "compliance") {
+          setFetchedPolicy(v);
+        }
+      } catch {
+      }
+    })();
+    return () => {
+      mounted = false;
+    };
+  }, [baseClient, mediaPolicy]);
+  const effectiveMediaPolicy = mediaPolicy ?? fetchedPolicy;
   useEffect(() => {
     const token = client.getSessionToken();
     if (token) {
@@ -7652,7 +7674,7 @@ function ScaleMuleProvider({
       photo: baseClient.photo,
       video: baseClient.video,
       audio: baseClient.audio,
-      mediaPolicy,
+      mediaPolicy: effectiveMediaPolicy,
       user,
       setUser: handleSetUser,
       initializing,
@@ -7667,7 +7689,7 @@ function ScaleMuleProvider({
       accountSwitcherPrivacy,
       bootstrapFlags
     }),
-    [client, money, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, mediaPolicy]
+    [client, money, baseClient, user, handleSetUser, initializing, error, analyticsProxyUrl, authProxyUrl, publishableKey, resolvedGatewayUrl, environment, enableAccountSwitcher, accountSwitcherPrivacy, bootstrapFlags, effectiveMediaPolicy]
   );
   return /* @__PURE__ */ jsx(ScaleMuleContext.Provider, { value, children });
 }
@@ -9083,10 +9105,13 @@ function useMedia() {
     async (fileId) => {
       setError(null);
       try {
-        const r = await storage.delete(fileId);
-        if (r.error) {
-          if (r.error.status === 404) return;
-          throw r.error;
+        const [, storageResult] = await Promise.all([
+          photo.delete(fileId).catch(() => void 0),
+          storage.delete(fileId)
+        ]);
+        if (storageResult.error) {
+          if (storageResult.error.status === 404) return;
+          throw storageResult.error;
         }
       } catch (err) {
         const e = err;
@@ -9094,13 +9119,32 @@ function useMedia() {
         throw e;
       }
     },
-    [storage]
+    [storage, photo]
   );
   return { upload, cancelUpload, error, uploading };
 }
+function conversationChannel(kind, id) {
+  switch (kind) {
+    case "large_room":
+      return `conversation:lr:${id}`;
+    case "broadcast":
+      return `conversation:bc:${id}`;
+    case "support":
+      return `conversation:support:${id}`;
+    case "standard":
+    default:
+      return `conversation:${id}`;
+  }
+}
 function useFileStatus(options) {
-  const { storage } = useScaleMule();
-  const { fileId, pollIntervalMs = null, disabled = false } = options;
+  const { storage, realtime } = useScaleMule();
+  const {
+    fileId,
+    pollIntervalMs = null,
+    disabled = false,
+    conversationId = null,
+    conversationKind = "standard"
+  } = options;
   const [status, setStatus] = useState(null);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState(null);
@@ -9132,13 +9176,40 @@ function useFileStatus(options) {
   }, [fetchStatus]);
   useEffect(() => {
     if (!pollIntervalMs || disabled || !fileId) return;
-    const isClean = status?.scan.status === "clean";
-    if (isClean) return;
+    const scan = status?.scan.status;
+    if (scan === "threat" || scan === "quarantined" || scan === "error") return;
+    const optimizePending = status?.optimize != null && status.optimize.status !== "done";
+    const transcodePending = status?.transcode != null && status.transcode.status !== "done";
+    const pipelinePending = optimizePending || transcodePending;
+    const isSettled = scan === "clean" && !pipelinePending;
+    if (isSettled) return;
     const id = setInterval(() => {
       void fetchStatus();
     }, pollIntervalMs);
     return () => clearInterval(id);
-  }, [pollIntervalMs, disabled, fileId, status?.scan.status, fetchStatus]);
+  }, [
+    pollIntervalMs,
+    disabled,
+    fileId,
+    status?.scan.status,
+    status?.optimize,
+    status?.transcode,
+    fetchStatus
+  ]);
+  useEffect(() => {
+    if (!conversationId || !fileId || disabled) return;
+    const channel = conversationChannel(conversationKind, conversationId);
+    const unsub = realtime.subscribe(channel, (data) => {
+      if (typeof data !== "object" || data === null) return;
+      const payload = data;
+      const wrapped = "data" in payload && typeof payload.data === "object" && payload.data !== null ? payload.data : payload;
+      const evt = typeof payload.event === "string" ? payload.event : void 0;
+      if (evt && evt !== "file_status_changed") return;
+      if (wrapped.file_id !== fileId) return;
+      void fetchStatus();
+    });
+    return unsub;
+  }, [realtime, conversationId, conversationKind, fileId, disabled, fetchStatus]);
   const isReady = status?.scan.status === "clean";
   return { status, loading, error, isReady, refresh: fetchStatus };
 }
@@ -9153,32 +9224,54 @@ function ScaleMuleMedia(props) {
     style,
     alt,
     pollIntervalMs = 2e3,
+    conversationId = null,
+    conversationKind,
     renderPlaceholder,
     renderBlocked,
     renderOverride
   } = props;
-  const { status, isReady } = useFileStatus({ fileId, pollIntervalMs });
+  const { gatewayUrl } = useScaleMule();
+  const { status, isReady } = useFileStatus({
+    fileId,
+    pollIntervalMs,
+    conversationId,
+    conversationKind
+  });
+  const absoluteUrl = React.useCallback(
+    (url) => {
+      if (!url) return null;
+      if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("blob:") || url.startsWith("data:")) {
+        return url;
+      }
+      if (!gatewayUrl) return url;
+      const base = gatewayUrl.endsWith("/") ? gatewayUrl.slice(0, -1) : gatewayUrl;
+      const path = url.startsWith("/") ? url : `/${url}`;
+      return `${base}${path}`;
+    },
+    [gatewayUrl]
+  );
   const isImage = mimeType.startsWith("image/");
   const isVideo = mimeType.startsWith("video/");
   const isAudio = mimeType.startsWith("audio/");
   const src = useMemo(() => {
     const scan = status?.scan.status;
     if (scan === "threat" || scan === "quarantined") return null;
-    if (status && isReady) {
-      if (isImage && status.urls.optimized) return status.urls.optimized;
-      if (isVideo && status.urls.hls) return status.urls.hls;
-      return status.urls.original ?? null;
-    }
-    if (blobPreview) return blobPreview;
-    return null;
-  }, [status, isReady, isImage, isVideo, blobPreview]);
+    if (!status) {
+      return blobPreview ?? null;
+    }
+    if (isImage && status.urls.optimized) return absoluteUrl(status.urls.optimized);
+    if (isVideo && status.urls.hls) return absoluteUrl(status.urls.hls);
+    if (status.urls.original) return absoluteUrl(status.urls.original);
+    return blobPreview ?? null;
+  }, [status, isImage, isVideo, blobPreview, absoluteUrl]);
   const renderState = useMemo(() => {
     const scan = status?.scan.status;
     if (scan === "threat" || scan === "quarantined") return "blocked";
+    if (status?.urls.original) return "ready";
     if (isReady) return "ready";
     if (blobPreview) return "preview";
     return "pending";
-  }, [status?.scan.status, isReady, blobPreview]);
+  }, [status?.scan.status, status?.urls.original, isReady, blobPreview]);
   const videoRef = React.useRef(null);
   useEffect(() => {
     if (!isVideo) return;

package/package.json

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