@scalemule/nextjs 0.1.7 → 0.1.9

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

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, FileStatus } from '@scalemule/sdk';
+import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, AudioService, FileStatus } from '@scalemule/sdk';
 import * as React from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
@@ -164,6 +164,8 @@ interface ScaleMuleContextValue {
     photo: PhotoService;
     /** Base SDK video service — exposed for `useMedia()` and `video.uploadViaStorage()` */
     video: VideoService;
+    /** Base SDK audio service — exposed for `useMedia()` and `audio.uploadViaStorage()` */
+    audio: AudioService;
     /**
      * Default media policy for `useMedia()` calls. Set via
      * `<ScaleMuleProvider mediaPolicy="…">`; per-call overrides win.
@@ -322,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. */
@@ -360,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;
 
@@ -411,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).
@@ -948,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

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, FileStatus } from '@scalemule/sdk';
+import { ApiError, RealtimeService, StorageService, PhotoService, VideoService, AudioService, FileStatus } from '@scalemule/sdk';
 import * as React from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
@@ -164,6 +164,8 @@ interface ScaleMuleContextValue {
     photo: PhotoService;
     /** Base SDK video service — exposed for `useMedia()` and `video.uploadViaStorage()` */
     video: VideoService;
+    /** Base SDK audio service — exposed for `useMedia()` and `audio.uploadViaStorage()` */
+    audio: AudioService;
     /**
      * Default media policy for `useMedia()` calls. Set via
      * `<ScaleMuleProvider mediaPolicy="…">`; per-call overrides win.
@@ -322,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. */
@@ -360,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;
 
@@ -411,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).
@@ -948,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

@@ -2727,6 +2727,25 @@ var StorageService = class extends ServiceModule {
   async getInfo(fileId, options) {
     return this._get(`/files/${fileId}/info`, options);
   }
+  /**
+   * Get the calling app's storage + media settings — content policy,
+   * retention, max upload size, and the per-app `media_policy`.
+   *
+   * `media_policy` drives release-gating in the SDK upload helpers:
+   * `fast_trusted` / `safe_visible` resolve immediately on upload; the
+   * `safe_public` / `moderated` / `compliance` modes await pipeline
+   * completion before resolving the upload promise.
+   */
+  async getSettings(options) {
+    return this._get("/settings", options);
+  }
+  /**
+   * Update the calling app's storage + media settings. Admin-only on the
+   * platform side (callers without the right role get 403).
+   */
+  async updateSettings(settings, options) {
+    return this.put("/settings", settings, options);
+  }
   /**
    * Aggregate status for a file — single call returns scan + reserved
    * optimize/transcode slots + the canonical view URL paths for image
@@ -5678,6 +5697,72 @@ var PhotoService = class extends ServiceModule {
     return this.get(id);
   }
 };
+var AudioService = class extends ServiceModule {
+  /**
+   * @param storage Required for {@link uploadViaStorage}. Wired up by the
+   *   top-level {@link ScaleMule} constructor — most call sites should not
+   *   instantiate `AudioService` directly.
+   */
+  constructor(client, storage) {
+    super(client);
+    this.storage = storage;
+    this.basePath = "/v1/audios";
+  }
+  /**
+   * Register a storage-uploaded audio asset with the audio service.
+   * Idempotent — re-calling with the same `file_id` returns the existing
+   * record.
+   */
+  async register(args, options) {
+    return this.post("/register", { file_id: args.fileId, sm_user_id: args.userId }, options);
+  }
+  /**
+   * Upload a file to storage (browser → S3 direct, private, uncompressed)
+   * and register it with the audio service.
+   *
+   * Mirrors `photo.uploadViaStorage()` / `video.uploadViaStorage()`. If
+   * `register()` fails after a successful storage upload, the file is *not*
+   * lost — the returned `file_id` is still valid as a generic private storage
+   * file. The SDK logs a warning and returns `audio_id: null`.
+   */
+  async uploadViaStorage(file, uploadOptions, requestOptions) {
+    const uploadResult = await this.storage.uploadPrivate(file, {
+      filename: uploadOptions?.filename,
+      metadata: uploadOptions?.metadata,
+      onProgress: uploadOptions?.onProgress,
+      signal: uploadOptions?.signal
+    });
+    if (uploadResult.error || !uploadResult.data) {
+      return { data: null, error: uploadResult.error };
+    }
+    const fileInfo = uploadResult.data;
+    const fileId = fileInfo.id;
+    const originalViewUrl = fileInfo.url ?? null;
+    const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
+    if (registerResult.error || !registerResult.data) {
+      console.warn(
+        "[scalemule-sdk] audio.register() failed after storage upload; typed audio metadata unavailable.",
+        registerResult.error
+      );
+      return {
+        data: {
+          file_id: fileId,
+          audio_id: null,
+          original_view_url: originalViewUrl
+        },
+        error: null
+      };
+    }
+    return {
+      data: {
+        file_id: fileId,
+        audio_id: registerResult.data.audio_id,
+        original_view_url: originalViewUrl
+      },
+      error: null
+    };
+  }
+};
 var DeadLetterApi = class extends ServiceModule {
   constructor() {
     super(...arguments);
@@ -6497,6 +6582,7 @@ var ScaleMule = class {
     this.graph = new GraphService(this._client);
     this.functions = new FunctionsService(this._client);
     this.photo = new PhotoService(this._client, this.storage);
+    this.audio = new AudioService(this._client, this.storage);
     this.flagContent = new FlagContentService(this._client);
     this.creatorMaker = new CreatorMakerService(this._client);
     this.compliance = new ComplianceService(this._client);
@@ -7585,6 +7671,7 @@ function ScaleMuleProvider({
       storage: baseClient.storage,
       photo: baseClient.photo,
       video: baseClient.video,
+      audio: baseClient.audio,
       mediaPolicy,
       user,
       setUser: handleSetUser,
@@ -8899,7 +8986,7 @@ function useContent(options = {}) {
   );
 }
 function useMedia() {
-  const { storage, photo, video, mediaPolicy: providerDefaultPolicy } = useScaleMule();
+  const { storage, photo, video, audio, mediaPolicy: providerDefaultPolicy } = useScaleMule();
   const [uploading, setUploading] = React.useState(false);
   const [error, setError] = React.useState(null);
   const upload = React.useCallback(
@@ -8953,6 +9040,21 @@ function useMedia() {
             is_public: false
           };
         }
+        if (mimeType.startsWith("audio/") && !isPublic) {
+          const r2 = await audio.uploadViaStorage(file, sharedOpts);
+          if (r2.error || !r2.data) {
+            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
+          }
+          return {
+            file_id: r2.data.file_id,
+            photo_id: null,
+            original_view_url: r2.data.original_view_url,
+            optimized_url_promise: Promise.resolve(null),
+            hls_url_promise: Promise.resolve(null),
+            mime_type: mimeType,
+            is_public: false
+          };
+        }
         if (mimeType.startsWith("image/") && isPublic) {
           const r2 = await storage.upload(file, {
             ...sharedOpts,
@@ -8995,7 +9097,7 @@ function useMedia() {
         setUploading(false);
       }
     },
-    [storage, photo, video, providerDefaultPolicy]
+    [storage, photo, video, audio, providerDefaultPolicy]
   );
   const cancelUpload = React.useCallback(
     async (fileId) => {
@@ -9016,9 +9118,28 @@ function useMedia() {
   );
   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);
@@ -9057,6 +9178,20 @@ function useFileStatus(options) {
     }, pollIntervalMs);
     return () => clearInterval(id);
   }, [pollIntervalMs, disabled, fileId, status?.scan.status, 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 };
 }
@@ -9071,11 +9206,18 @@ function ScaleMuleMedia(props) {
     style,
     alt,
     pollIntervalMs = 2e3,
+    conversationId = null,
+    conversationKind,
     renderPlaceholder,
     renderBlocked,
     renderOverride
   } = props;
-  const { status, isReady } = useFileStatus({ fileId, pollIntervalMs });
+  const { status, isReady } = useFileStatus({
+    fileId,
+    pollIntervalMs,
+    conversationId,
+    conversationKind
+  });
   const isImage = mimeType.startsWith("image/");
   const isVideo = mimeType.startsWith("video/");
   const isAudio = mimeType.startsWith("audio/");

package/dist/index.mjs

@@ -2707,6 +2707,25 @@ var StorageService = class extends ServiceModule {
   async getInfo(fileId, options) {
     return this._get(`/files/${fileId}/info`, options);
   }
+  /**
+   * Get the calling app's storage + media settings — content policy,
+   * retention, max upload size, and the per-app `media_policy`.
+   *
+   * `media_policy` drives release-gating in the SDK upload helpers:
+   * `fast_trusted` / `safe_visible` resolve immediately on upload; the
+   * `safe_public` / `moderated` / `compliance` modes await pipeline
+   * completion before resolving the upload promise.
+   */
+  async getSettings(options) {
+    return this._get("/settings", options);
+  }
+  /**
+   * Update the calling app's storage + media settings. Admin-only on the
+   * platform side (callers without the right role get 403).
+   */
+  async updateSettings(settings, options) {
+    return this.put("/settings", settings, options);
+  }
   /**
    * Aggregate status for a file — single call returns scan + reserved
    * optimize/transcode slots + the canonical view URL paths for image
@@ -5658,6 +5677,72 @@ var PhotoService = class extends ServiceModule {
     return this.get(id);
   }
 };
+var AudioService = class extends ServiceModule {
+  /**
+   * @param storage Required for {@link uploadViaStorage}. Wired up by the
+   *   top-level {@link ScaleMule} constructor — most call sites should not
+   *   instantiate `AudioService` directly.
+   */
+  constructor(client, storage) {
+    super(client);
+    this.storage = storage;
+    this.basePath = "/v1/audios";
+  }
+  /**
+   * Register a storage-uploaded audio asset with the audio service.
+   * Idempotent — re-calling with the same `file_id` returns the existing
+   * record.
+   */
+  async register(args, options) {
+    return this.post("/register", { file_id: args.fileId, sm_user_id: args.userId }, options);
+  }
+  /**
+   * Upload a file to storage (browser → S3 direct, private, uncompressed)
+   * and register it with the audio service.
+   *
+   * Mirrors `photo.uploadViaStorage()` / `video.uploadViaStorage()`. If
+   * `register()` fails after a successful storage upload, the file is *not*
+   * lost — the returned `file_id` is still valid as a generic private storage
+   * file. The SDK logs a warning and returns `audio_id: null`.
+   */
+  async uploadViaStorage(file, uploadOptions, requestOptions) {
+    const uploadResult = await this.storage.uploadPrivate(file, {
+      filename: uploadOptions?.filename,
+      metadata: uploadOptions?.metadata,
+      onProgress: uploadOptions?.onProgress,
+      signal: uploadOptions?.signal
+    });
+    if (uploadResult.error || !uploadResult.data) {
+      return { data: null, error: uploadResult.error };
+    }
+    const fileInfo = uploadResult.data;
+    const fileId = fileInfo.id;
+    const originalViewUrl = fileInfo.url ?? null;
+    const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
+    if (registerResult.error || !registerResult.data) {
+      console.warn(
+        "[scalemule-sdk] audio.register() failed after storage upload; typed audio metadata unavailable.",
+        registerResult.error
+      );
+      return {
+        data: {
+          file_id: fileId,
+          audio_id: null,
+          original_view_url: originalViewUrl
+        },
+        error: null
+      };
+    }
+    return {
+      data: {
+        file_id: fileId,
+        audio_id: registerResult.data.audio_id,
+        original_view_url: originalViewUrl
+      },
+      error: null
+    };
+  }
+};
 var DeadLetterApi = class extends ServiceModule {
   constructor() {
     super(...arguments);
@@ -6477,6 +6562,7 @@ var ScaleMule = class {
     this.graph = new GraphService(this._client);
     this.functions = new FunctionsService(this._client);
     this.photo = new PhotoService(this._client, this.storage);
+    this.audio = new AudioService(this._client, this.storage);
     this.flagContent = new FlagContentService(this._client);
     this.creatorMaker = new CreatorMakerService(this._client);
     this.compliance = new ComplianceService(this._client);
@@ -7565,6 +7651,7 @@ function ScaleMuleProvider({
       storage: baseClient.storage,
       photo: baseClient.photo,
       video: baseClient.video,
+      audio: baseClient.audio,
       mediaPolicy,
       user,
       setUser: handleSetUser,
@@ -8879,7 +8966,7 @@ function useContent(options = {}) {
   );
 }
 function useMedia() {
-  const { storage, photo, video, mediaPolicy: providerDefaultPolicy } = useScaleMule();
+  const { storage, photo, video, audio, mediaPolicy: providerDefaultPolicy } = useScaleMule();
   const [uploading, setUploading] = useState(false);
   const [error, setError] = useState(null);
   const upload = useCallback(
@@ -8933,6 +9020,21 @@ function useMedia() {
             is_public: false
           };
         }
+        if (mimeType.startsWith("audio/") && !isPublic) {
+          const r2 = await audio.uploadViaStorage(file, sharedOpts);
+          if (r2.error || !r2.data) {
+            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
+          }
+          return {
+            file_id: r2.data.file_id,
+            photo_id: null,
+            original_view_url: r2.data.original_view_url,
+            optimized_url_promise: Promise.resolve(null),
+            hls_url_promise: Promise.resolve(null),
+            mime_type: mimeType,
+            is_public: false
+          };
+        }
         if (mimeType.startsWith("image/") && isPublic) {
           const r2 = await storage.upload(file, {
             ...sharedOpts,
@@ -8975,7 +9077,7 @@ function useMedia() {
         setUploading(false);
       }
     },
-    [storage, photo, video, providerDefaultPolicy]
+    [storage, photo, video, audio, providerDefaultPolicy]
   );
   const cancelUpload = useCallback(
     async (fileId) => {
@@ -8996,9 +9098,28 @@ function useMedia() {
   );
   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);
@@ -9037,6 +9158,20 @@ function useFileStatus(options) {
     }, pollIntervalMs);
     return () => clearInterval(id);
   }, [pollIntervalMs, disabled, fileId, status?.scan.status, 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 };
 }
@@ -9051,11 +9186,18 @@ function ScaleMuleMedia(props) {
     style,
     alt,
     pollIntervalMs = 2e3,
+    conversationId = null,
+    conversationKind,
     renderPlaceholder,
     renderBlocked,
     renderOverride
   } = props;
-  const { status, isReady } = useFileStatus({ fileId, pollIntervalMs });
+  const { status, isReady } = useFileStatus({
+    fileId,
+    pollIntervalMs,
+    conversationId,
+    conversationKind
+  });
   const isImage = mimeType.startsWith("image/");
   const isVideo = mimeType.startsWith("video/");
   const isAudio = mimeType.startsWith("audio/");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalemule/nextjs",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "ScaleMule SDK for Next.js applications - authentication, storage, and user management",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -54,7 +54,7 @@
   },
   "dependencies": {
     "@scalemule/money": "^0.0.1",
-    "@scalemule/sdk": "^0.0.41"
+    "@scalemule/sdk": "^0.0.43"
   },
   "peerDependencies": {
     "next": ">=14.0.0",