@scalemule/nextjs 0.1.3 → 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, VideoService, 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';
@@ -268,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;
 
 /**
@@ -751,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, VideoService, 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';
@@ -268,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;
 
 /**
@@ -751,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.
@@ -8961,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;
@@ -10771,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.
@@ -8960,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;
@@ -10746,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.3",
+  "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.39"
+    "@scalemule/sdk": "^0.0.41"
   },
   "peerDependencies": {
     "next": ">=14.0.0",