@scalemule/nextjs 0.1.2 → 0.1.4

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
 export { MoneyClient, MoneyClientConfig, createMoneyClient } from '@scalemule/money';
-import { RealtimeService, StorageService, PhotoService, ApiError as ApiError$1 } from '@scalemule/sdk';
+import { RealtimeService, StorageService, PhotoService, VideoService, ApiError as ApiError$1, FileStatus } from '@scalemule/sdk';
 import { ScaleMuleClient } from './client.mjs';
 export { ClientConfig, RequestOptions, createClient } from './client.mjs';
 import { S as ScaleMuleConfig, U as User, L as LoginResponse, A as ApiError, a as UseAuthReturn, b as UseBillingReturn, c as ListFilesParams, d as UseContentReturn, e as UseUserReturn, f as UseAnalyticsOptions, g as UseAnalyticsReturn } from './index-BIIUrnPr.mjs';
@@ -19,6 +19,8 @@ interface ScaleMuleContextValue {
     storage: StorageService;
     /** Base SDK photo service — exposed for `useMedia()` and `photo.uploadViaStorage()` */
     photo: PhotoService;
+    /** Base SDK video service — exposed for `useMedia()` and `video.uploadViaStorage()` */
+    video: VideoService;
     /** Current authenticated user */
     user: User | null;
     /** Set the current user */
@@ -266,6 +268,70 @@ interface UseMediaReturn {
  */
 declare function useMedia(): UseMediaReturn;
 
+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.
+     */
+    pollIntervalMs?: number | null;
+    /**
+     * Disable the hook (don't fetch). Useful when `fileId` is conditional.
+     */
+    disabled?: boolean;
+}
+interface UseFileStatusReturn {
+    /** The latest status response, or null on first render / disabled. */
+    status: FileStatus | null;
+    /** True while a fetch is in flight. */
+    loading: boolean;
+    /** Last error, or null. */
+    error: ApiError$1 | null;
+    /**
+     * Convenience: scan is clean. For images/videos, this means the file
+     * is *safe to render*; the optimized / HLS variants may still be
+     * processing. The caller should attempt the constructed URLs and
+     * fall back to `urls.original` if the pipeline-specific URL 404s.
+     */
+    isReady: boolean;
+    /** Force-refresh the status. Promise resolves when the new state is committed. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribes to {@link FileStatus} for a single file. Today this is a
+ * pull-only hook — single fetch by default, optional polling.
+ *
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * function ChatImage({ fileId }: { fileId: string }) {
+ *   const { status, isReady } = useFileStatus({
+ *     fileId,
+ *     pollIntervalMs: 2000,
+ *   });
+ *   if (!isReady) return <div>Scanning…</div>;
+ *   const src = status?.urls.optimized ?? status?.urls.original;
+ *   return <img src={src} />;
+ * }
+ * ```
+ */
+declare function useFileStatus(options: UseFileStatusOptions): UseFileStatusReturn;
+
 declare const useMoney: typeof useMoneyClient;
 
 /**
@@ -749,4 +815,4 @@ declare function createSafeLogger(prefix: string): {
     error: (message: string, data?: unknown) => void;
 };
 
-export { 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 MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, ScaleMuleProvider, type ScaleMuleProviderProps, UseAnalyticsOptions, UseAnalyticsReturn, UseAuthReturn, UseBillingReturn, UseContentReturn, type UseFeatureFlagsOptions, type UseFeatureFlagsReturn, type UseFeedbackOptions, type UseFeedbackResult, 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, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };
+export { 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 MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, 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

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
 export { MoneyClient, MoneyClientConfig, createMoneyClient } from '@scalemule/money';
-import { RealtimeService, StorageService, PhotoService, ApiError as ApiError$1 } from '@scalemule/sdk';
+import { RealtimeService, StorageService, PhotoService, VideoService, ApiError as ApiError$1, FileStatus } from '@scalemule/sdk';
 import { ScaleMuleClient } from './client.js';
 export { ClientConfig, RequestOptions, createClient } from './client.js';
 import { S as ScaleMuleConfig, U as User, L as LoginResponse, A as ApiError, a as UseAuthReturn, b as UseBillingReturn, c as ListFilesParams, d as UseContentReturn, e as UseUserReturn, f as UseAnalyticsOptions, g as UseAnalyticsReturn } from './index-BIIUrnPr.js';
@@ -19,6 +19,8 @@ interface ScaleMuleContextValue {
     storage: StorageService;
     /** Base SDK photo service — exposed for `useMedia()` and `photo.uploadViaStorage()` */
     photo: PhotoService;
+    /** Base SDK video service — exposed for `useMedia()` and `video.uploadViaStorage()` */
+    video: VideoService;
     /** Current authenticated user */
     user: User | null;
     /** Set the current user */
@@ -266,6 +268,70 @@ interface UseMediaReturn {
  */
 declare function useMedia(): UseMediaReturn;
 
+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.
+     */
+    pollIntervalMs?: number | null;
+    /**
+     * Disable the hook (don't fetch). Useful when `fileId` is conditional.
+     */
+    disabled?: boolean;
+}
+interface UseFileStatusReturn {
+    /** The latest status response, or null on first render / disabled. */
+    status: FileStatus | null;
+    /** True while a fetch is in flight. */
+    loading: boolean;
+    /** Last error, or null. */
+    error: ApiError$1 | null;
+    /**
+     * Convenience: scan is clean. For images/videos, this means the file
+     * is *safe to render*; the optimized / HLS variants may still be
+     * processing. The caller should attempt the constructed URLs and
+     * fall back to `urls.original` if the pipeline-specific URL 404s.
+     */
+    isReady: boolean;
+    /** Force-refresh the status. Promise resolves when the new state is committed. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribes to {@link FileStatus} for a single file. Today this is a
+ * pull-only hook — single fetch by default, optional polling.
+ *
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * function ChatImage({ fileId }: { fileId: string }) {
+ *   const { status, isReady } = useFileStatus({
+ *     fileId,
+ *     pollIntervalMs: 2000,
+ *   });
+ *   if (!isReady) return <div>Scanning…</div>;
+ *   const src = status?.urls.optimized ?? status?.urls.original;
+ *   return <img src={src} />;
+ * }
+ * ```
+ */
+declare function useFileStatus(options: UseFileStatusOptions): UseFileStatusReturn;
+
 declare const useMoney: typeof useMoneyClient;
 
 /**
@@ -749,4 +815,4 @@ declare function createSafeLogger(prefix: string): {
     error: (message: string, data?: unknown) => void;
 };
 
-export { 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 MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, ScaleMuleProvider, type ScaleMuleProviderProps, UseAnalyticsOptions, UseAnalyticsReturn, UseAuthReturn, UseBillingReturn, UseContentReturn, type UseFeatureFlagsOptions, type UseFeatureFlagsReturn, type UseFeedbackOptions, type UseFeedbackResult, 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, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };
+export { 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 MediaUploadResult, type PasswordValidationResult, type PhoneCountry, type PhoneValidationResult, type RealtimeEvent, type RealtimeMessage, type RealtimeStatus, ScaleMuleClient, ScaleMuleConfig, 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

@@ -2707,6 +2707,31 @@ var StorageService = class extends ServiceModule {
   async getInfo(fileId, options) {
     return this._get(`/files/${fileId}/info`, options);
   }
+  /**
+   * Aggregate status for a file — single call returns scan + reserved
+   * optimize/transcode slots + the canonical view URL paths for image
+   * (transform endpoint) and video (HLS playlist) MIME types.
+   *
+   * Foundational primitive for the chat / progressive media read side.
+   * `useFileStatus()` (in `@scalemule/nextjs`) consumes this for both
+   * first-paint and refresh-on-demand scenarios.
+   *
+   * `optimize` and `transcode` are reserved for Phase 3 enrichment. Until
+   * the photo/video services expose internal status endpoints, callers
+   * should attempt the constructed URLs directly to discover readiness
+   * (404 means the pipeline is still running).
+   *
+   * @example
+   * ```ts
+   * const r = await client.storage.getFileStatus(fileId);
+   * if (r.data?.scan.status === 'clean' && r.data.urls.optimized) {
+   *   // image: try transform URL for an optimized variant
+   * }
+   * ```
+   */
+  async getFileStatus(fileId, options) {
+    return this._get(`/files/${fileId}/status`, options);
+  }
   /**
    * Get a signed view URL for inline display (img src, thumbnails).
    * Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
@@ -3505,8 +3530,13 @@ var RealtimeService = class extends ServiceModule {
 var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
 var MIN_CHUNK_SIZE = 5 * 1024 * 1024;
 var VideoService = class extends ServiceModule {
-  constructor() {
-    super(...arguments);
+  /**
+   * @param storage Required for {@link uploadViaStorage}. Wired up by the
+   *   top-level {@link ScaleMule} constructor.
+   */
+  constructor(client, storage) {
+    super(client);
+    this.storage = storage;
     this.basePath = "/v1/videos";
   }
   // --------------------------------------------------------------------------
@@ -3580,6 +3610,115 @@ var VideoService = class extends ServiceModule {
   async get(videoId, options) {
     return super._get(`/${videoId}`, options);
   }
+  /**
+   * Register a video from a file already uploaded to scalemule-storage.
+   *
+   * The synchronous handshake for storage-uploaded videos. Verifies the
+   * caller's app owns the storage `file_id` and reads scan status:
+   *   - clean   → 201, video record created with status='uploading',
+   *               transcode worker advances on `scan.file.completed`
+   *   - pending → 202, video record created with status='pending_scan',
+   *               worker advances when scan completes
+   *   - threat  → 409 (rejected; row not created)
+   *
+   * Idempotent: calling twice with the same file_id returns the existing
+   * row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
+   *
+   * For storage-backed videos `video_id == file_id` — the response's
+   * `video_id` and `file_id` are identical, and either can be used with
+   * `getStreamUrl()` / `get()`.
+   *
+   * Most callers should use {@link uploadViaStorage} which composes
+   * `storage.uploadPrivate()` + `register()` in a single call.
+   */
+  async register(request, options) {
+    return this.post(
+      "/register",
+      {
+        file_id: request.fileId,
+        sm_user_id: request.userId
+      },
+      options
+    );
+  }
+  /**
+   * Upload a video to storage (browser → S3 direct, private, no
+   * compression) and register it with the video service so transcoding
+   * + HLS streaming work.
+   *
+   * The canonical chat-attachment / progressive-video upload primitive.
+   * Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
+   * follow-up `video.register()` call so HLS playback URLs become live
+   * once the transcoder finishes.
+   *
+   * The returned `hls_url_promise` resolves once the video's status
+   * flips to `ready` (or after a 30s timeout — caller can still serve
+   * `original_view_url` as the fallback). Phase 3 of the realtime-chat
+   * media pipeline ADR replaces the poll with a realtime subscription.
+   *
+   * If `register()` fails after a successful storage upload, the file
+   * is *not* lost: the returned `file_id` is still valid as a generic
+   * storage file. SDK logs a warning and resolves `hls_url_promise`
+   * to `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] video.register() failed after storage upload; HLS variants unavailable.",
+        registerResult.error
+      );
+      return {
+        data: {
+          file_id: fileId,
+          video_id: fileId,
+          original_view_url: originalViewUrl,
+          hls_url_promise: Promise.resolve(null)
+        },
+        error: null
+      };
+    }
+    const videoId = registerResult.data.video_id;
+    const hlsUrlPromise = this.pollTranscodeComplete(videoId, requestOptions);
+    return {
+      data: {
+        file_id: fileId,
+        video_id: videoId,
+        original_view_url: originalViewUrl,
+        hls_url_promise: hlsUrlPromise
+      },
+      error: null
+    };
+  }
+  /**
+   * Poll {@link get} until the video's status is `ready` or the 30s
+   * timeout fires. Resolves to the HLS master playlist URL on success;
+   * `null` on timeout (caller should fall back to `original_view_url`).
+   */
+  async pollTranscodeComplete(videoId, requestOptions) {
+    const intervalMs = 1e3;
+    const maxAttempts = 30;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const result = await this.get(videoId, requestOptions);
+      if (result.data?.status === "ready") {
+        return `${this.client.getBaseUrl()}${this.basePath}/${videoId}/playlist.m3u8`;
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return null;
+  }
   /**
    * Get the HLS master playlist URL for streaming.
    * Returns the playlist URL that can be passed to a video player.
@@ -6310,7 +6449,7 @@ var ScaleMule = class {
     this.auth = new AuthService(this._client);
     this.storage = new StorageService(this._client);
     this.realtime = new RealtimeService(this._client);
-    this.video = new VideoService(this._client);
+    this.video = new VideoService(this._client, this.storage);
     this.data = new DataService(this._client);
     this.chat = new ChatService(this._client);
     this.conference = new ConferenceService(this._client);
@@ -7424,6 +7563,7 @@ function ScaleMuleProvider({
       realtime: baseClient.realtime,
       storage: baseClient.storage,
       photo: baseClient.photo,
+      video: baseClient.video,
       user,
       setUser: handleSetUser,
       initializing,
@@ -8737,7 +8877,7 @@ function useContent(options = {}) {
   );
 }
 function useMedia() {
-  const { storage, photo } = useScaleMule();
+  const { storage, photo, video } = useScaleMule();
   const [uploading, setUploading] = react.useState(false);
   const [error, setError] = react.useState(null);
   const upload = react.useCallback(
@@ -8768,6 +8908,21 @@ function useMedia() {
             is_public: false
           };
         }
+        if (mimeType.startsWith("video/") && !isPublic) {
+          const r2 = await video.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: r2.data.hls_url_promise,
+            mime_type: mimeType,
+            is_public: false
+          };
+        }
         if (mimeType.startsWith("image/") && isPublic) {
           const r2 = await storage.upload(file, {
             ...sharedOpts,
@@ -8831,6 +8986,50 @@ function useMedia() {
   );
   return { upload, cancelUpload, error, uploading };
 }
+function useFileStatus(options) {
+  const { storage } = useScaleMule();
+  const { fileId, pollIntervalMs = null, disabled = false } = options;
+  const [status, setStatus] = react.useState(null);
+  const [loading, setLoading] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  const requestSeqRef = react.useRef(0);
+  const fetchStatus = react.useCallback(async () => {
+    if (!fileId || disabled) return;
+    const seq = ++requestSeqRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const r = await storage.getFileStatus(fileId);
+      if (seq !== requestSeqRef.current) return;
+      if (r.error || !r.data) {
+        setError(r.error);
+        return;
+      }
+      setStatus(r.data);
+    } catch (err) {
+      if (seq !== requestSeqRef.current) return;
+      setError(err);
+    } finally {
+      if (seq === requestSeqRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [storage, fileId, disabled]);
+  react.useEffect(() => {
+    void fetchStatus();
+  }, [fetchStatus]);
+  react.useEffect(() => {
+    if (!pollIntervalMs || disabled || !fileId) return;
+    const isClean = status?.scan.status === "clean";
+    if (isClean) return;
+    const id = setInterval(() => {
+      void fetchStatus();
+    }, pollIntervalMs);
+    return () => clearInterval(id);
+  }, [pollIntervalMs, disabled, fileId, status?.scan.status, fetchStatus]);
+  const isReady = status?.scan.status === "clean";
+  return { status, loading, error, isReady, refresh: fetchStatus };
+}
 
 // src/hooks/useMoney.ts
 var useMoney = useMoneyClient;
@@ -10641,6 +10840,7 @@ exports.useBilling = useBilling;
 exports.useContent = useContent;
 exports.useFeatureFlags = useFeatureFlags;
 exports.useFeedback = useFeedback;
+exports.useFileStatus = useFileStatus;
 exports.useMedia = useMedia;
 exports.useMoney = useMoney;
 exports.useMoneyClient = useMoneyClient;

package/dist/index.mjs

@@ -2706,6 +2706,31 @@ var StorageService = class extends ServiceModule {
   async getInfo(fileId, options) {
     return this._get(`/files/${fileId}/info`, options);
   }
+  /**
+   * Aggregate status for a file — single call returns scan + reserved
+   * optimize/transcode slots + the canonical view URL paths for image
+   * (transform endpoint) and video (HLS playlist) MIME types.
+   *
+   * Foundational primitive for the chat / progressive media read side.
+   * `useFileStatus()` (in `@scalemule/nextjs`) consumes this for both
+   * first-paint and refresh-on-demand scenarios.
+   *
+   * `optimize` and `transcode` are reserved for Phase 3 enrichment. Until
+   * the photo/video services expose internal status endpoints, callers
+   * should attempt the constructed URLs directly to discover readiness
+   * (404 means the pipeline is still running).
+   *
+   * @example
+   * ```ts
+   * const r = await client.storage.getFileStatus(fileId);
+   * if (r.data?.scan.status === 'clean' && r.data.urls.optimized) {
+   *   // image: try transform URL for an optimized variant
+   * }
+   * ```
+   */
+  async getFileStatus(fileId, options) {
+    return this._get(`/files/${fileId}/status`, options);
+  }
   /**
    * Get a signed view URL for inline display (img src, thumbnails).
    * Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
@@ -3504,8 +3529,13 @@ var RealtimeService = class extends ServiceModule {
 var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
 var MIN_CHUNK_SIZE = 5 * 1024 * 1024;
 var VideoService = class extends ServiceModule {
-  constructor() {
-    super(...arguments);
+  /**
+   * @param storage Required for {@link uploadViaStorage}. Wired up by the
+   *   top-level {@link ScaleMule} constructor.
+   */
+  constructor(client, storage) {
+    super(client);
+    this.storage = storage;
     this.basePath = "/v1/videos";
   }
   // --------------------------------------------------------------------------
@@ -3579,6 +3609,115 @@ var VideoService = class extends ServiceModule {
   async get(videoId, options) {
     return super._get(`/${videoId}`, options);
   }
+  /**
+   * Register a video from a file already uploaded to scalemule-storage.
+   *
+   * The synchronous handshake for storage-uploaded videos. Verifies the
+   * caller's app owns the storage `file_id` and reads scan status:
+   *   - clean   → 201, video record created with status='uploading',
+   *               transcode worker advances on `scan.file.completed`
+   *   - pending → 202, video record created with status='pending_scan',
+   *               worker advances when scan completes
+   *   - threat  → 409 (rejected; row not created)
+   *
+   * Idempotent: calling twice with the same file_id returns the existing
+   * row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
+   *
+   * For storage-backed videos `video_id == file_id` — the response's
+   * `video_id` and `file_id` are identical, and either can be used with
+   * `getStreamUrl()` / `get()`.
+   *
+   * Most callers should use {@link uploadViaStorage} which composes
+   * `storage.uploadPrivate()` + `register()` in a single call.
+   */
+  async register(request, options) {
+    return this.post(
+      "/register",
+      {
+        file_id: request.fileId,
+        sm_user_id: request.userId
+      },
+      options
+    );
+  }
+  /**
+   * Upload a video to storage (browser → S3 direct, private, no
+   * compression) and register it with the video service so transcoding
+   * + HLS streaming work.
+   *
+   * The canonical chat-attachment / progressive-video upload primitive.
+   * Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
+   * follow-up `video.register()` call so HLS playback URLs become live
+   * once the transcoder finishes.
+   *
+   * The returned `hls_url_promise` resolves once the video's status
+   * flips to `ready` (or after a 30s timeout — caller can still serve
+   * `original_view_url` as the fallback). Phase 3 of the realtime-chat
+   * media pipeline ADR replaces the poll with a realtime subscription.
+   *
+   * If `register()` fails after a successful storage upload, the file
+   * is *not* lost: the returned `file_id` is still valid as a generic
+   * storage file. SDK logs a warning and resolves `hls_url_promise`
+   * to `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] video.register() failed after storage upload; HLS variants unavailable.",
+        registerResult.error
+      );
+      return {
+        data: {
+          file_id: fileId,
+          video_id: fileId,
+          original_view_url: originalViewUrl,
+          hls_url_promise: Promise.resolve(null)
+        },
+        error: null
+      };
+    }
+    const videoId = registerResult.data.video_id;
+    const hlsUrlPromise = this.pollTranscodeComplete(videoId, requestOptions);
+    return {
+      data: {
+        file_id: fileId,
+        video_id: videoId,
+        original_view_url: originalViewUrl,
+        hls_url_promise: hlsUrlPromise
+      },
+      error: null
+    };
+  }
+  /**
+   * Poll {@link get} until the video's status is `ready` or the 30s
+   * timeout fires. Resolves to the HLS master playlist URL on success;
+   * `null` on timeout (caller should fall back to `original_view_url`).
+   */
+  async pollTranscodeComplete(videoId, requestOptions) {
+    const intervalMs = 1e3;
+    const maxAttempts = 30;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const result = await this.get(videoId, requestOptions);
+      if (result.data?.status === "ready") {
+        return `${this.client.getBaseUrl()}${this.basePath}/${videoId}/playlist.m3u8`;
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return null;
+  }
   /**
    * Get the HLS master playlist URL for streaming.
    * Returns the playlist URL that can be passed to a video player.
@@ -6309,7 +6448,7 @@ var ScaleMule = class {
     this.auth = new AuthService(this._client);
     this.storage = new StorageService(this._client);
     this.realtime = new RealtimeService(this._client);
-    this.video = new VideoService(this._client);
+    this.video = new VideoService(this._client, this.storage);
     this.data = new DataService(this._client);
     this.chat = new ChatService(this._client);
     this.conference = new ConferenceService(this._client);
@@ -7423,6 +7562,7 @@ function ScaleMuleProvider({
       realtime: baseClient.realtime,
       storage: baseClient.storage,
       photo: baseClient.photo,
+      video: baseClient.video,
       user,
       setUser: handleSetUser,
       initializing,
@@ -8736,7 +8876,7 @@ function useContent(options = {}) {
   );
 }
 function useMedia() {
-  const { storage, photo } = useScaleMule();
+  const { storage, photo, video } = useScaleMule();
   const [uploading, setUploading] = useState(false);
   const [error, setError] = useState(null);
   const upload = useCallback(
@@ -8767,6 +8907,21 @@ function useMedia() {
             is_public: false
           };
         }
+        if (mimeType.startsWith("video/") && !isPublic) {
+          const r2 = await video.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: r2.data.hls_url_promise,
+            mime_type: mimeType,
+            is_public: false
+          };
+        }
         if (mimeType.startsWith("image/") && isPublic) {
           const r2 = await storage.upload(file, {
             ...sharedOpts,
@@ -8830,6 +8985,50 @@ function useMedia() {
   );
   return { upload, cancelUpload, error, uploading };
 }
+function useFileStatus(options) {
+  const { storage } = useScaleMule();
+  const { fileId, pollIntervalMs = null, disabled = false } = options;
+  const [status, setStatus] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const requestSeqRef = useRef(0);
+  const fetchStatus = useCallback(async () => {
+    if (!fileId || disabled) return;
+    const seq = ++requestSeqRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const r = await storage.getFileStatus(fileId);
+      if (seq !== requestSeqRef.current) return;
+      if (r.error || !r.data) {
+        setError(r.error);
+        return;
+      }
+      setStatus(r.data);
+    } catch (err) {
+      if (seq !== requestSeqRef.current) return;
+      setError(err);
+    } finally {
+      if (seq === requestSeqRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [storage, fileId, disabled]);
+  useEffect(() => {
+    void fetchStatus();
+  }, [fetchStatus]);
+  useEffect(() => {
+    if (!pollIntervalMs || disabled || !fileId) return;
+    const isClean = status?.scan.status === "clean";
+    if (isClean) return;
+    const id = setInterval(() => {
+      void fetchStatus();
+    }, pollIntervalMs);
+    return () => clearInterval(id);
+  }, [pollIntervalMs, disabled, fileId, status?.scan.status, fetchStatus]);
+  const isReady = status?.scan.status === "clean";
+  return { status, loading, error, isReady, refresh: fetchStatus };
+}
 
 // src/hooks/useMoney.ts
 var useMoney = useMoneyClient;
@@ -10616,4 +10815,4 @@ function createSafeLogger(prefix) {
   };
 }
 
-export { FeedbackWidget, ScaleMuleApiError, ScaleMuleClient2 as ScaleMuleClient, ScaleMuleProvider, composePhone, createClient, createSafeLogger, normalizePhone, phoneCountries, sanitizeForLog, useAnalytics, useAuth, useBilling, useContent, useFeatureFlags, useFeedback, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };
+export { FeedbackWidget, ScaleMuleApiError, ScaleMuleClient2 as ScaleMuleClient, ScaleMuleProvider, composePhone, createClient, createSafeLogger, normalizePhone, phoneCountries, sanitizeForLog, useAnalytics, useAuth, useBilling, useContent, useFeatureFlags, useFeedback, useFileStatus, useMedia, useMoney, useMoneyClient, usePushNotifications, useRealtime, useScaleMule, useScaleMuleClient, useShare, useUser, validateForm, validators };

package/package.json

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