@scalemule/nextjs 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
 export { MoneyClient, MoneyClientConfig, createMoneyClient } from '@scalemule/money';
@@ -184,12 +185,43 @@ interface MediaUploadResult {
     /** Whether the resulting storage object is public-readable. */
     is_public: boolean;
 }
+/**
+ * Per-app media-pipeline policy. Drives release-gating + processing
+ * behavior. **Orthogonal to `is_public`.** See
+ * `docs/MEDIA-UPLOADS.md` and ADR-2026-04-26 for the full taxonomy.
+ *
+ * Today's behavior (Phase 4 v1):
+ *   - `fast_trusted` / `safe_visible` (default): upload promise resolves
+ *     as soon as the file is uploaded + registered. The post-processing
+ *     (scan, optimize, transcode) runs async; callers can observe via
+ *     `useFileStatus`.
+ *   - `safe_public` / `moderated`: upload promise *waits* for the
+ *     optimized image variant (image MIME) or HLS playlist (video MIME)
+ *     to become ready before resolving. Acts as the release-gate for
+ *     UGC-style apps that should not publish raw bytes.
+ *   - `compliance`: today behaves as `safe_public`; Phase 4+ adds the
+ *     audit-log + signed-with-purpose URL semantics.
+ */
+type MediaPolicy = 'fast_trusted' | 'safe_visible' | 'safe_public' | 'moderated' | 'compliance';
 interface UseMediaUploadOptions {
     /** Whether the resulting storage object should be public-readable.
      * Default: `false` (private). Public is opt-in for surfaces that
      * genuinely need it (avatars, public listings). Chat / DM uploads
      * should always be private. */
     is_public?: boolean;
+    /**
+     * Per-call media-policy override. Defaults to `safe_visible` (visible
+     * immediately at original fidelity; optimized variants swap in async).
+     * Set to `safe_public` to make the upload promise *await* the optimized
+     * variant (image) or HLS playlist (video) before resolving — useful for
+     * broadcast / UGC apps that gate publication on processing complete.
+     *
+     * The per-app default lives in `application_storage_settings.media_policy`
+     * (Phase 4 / P3, live in prod 2026-04-26). Reading the per-app default
+     * into `useMedia` defaults lands in a follow-up; today the option is
+     * caller-provided per call.
+     */
+    policy?: MediaPolicy;
     /** Display filename (sanitized server-side). */
     filename?: string;
     /** Custom metadata attached to the file. */
@@ -332,6 +364,85 @@ interface UseFileStatusReturn {
  */
 declare function useFileStatus(options: UseFileStatusOptions): UseFileStatusReturn;
 
+interface ScaleMuleMediaProps {
+    /** Storage `file_id` of the media to render. Required. */
+    fileId: string;
+    /** MIME type — drives which element to render. Required. */
+    mimeType: string;
+    /**
+     * Optional sender-side optimistic preview. While the upload is in
+     * progress (or the recipient hasn't yet observed the message), the
+     * component renders this Blob URL. Once `useFileStatus` resolves a
+     * scan-clean state and a server-side URL, the component swaps to it.
+     */
+    blobPreview?: string;
+    /** Display width hint (CSS pixels). Used for image breakpoint selection. */
+    width?: number;
+    /** Display height hint (CSS pixels). */
+    height?: number;
+    /** Pass-through className for the rendered element. */
+    className?: string;
+    /** Pass-through style. */
+    style?: React.CSSProperties;
+    /** Alt text for `<img>`; aria-label for `<audio>` / `<video>`. */
+    alt?: string;
+    /**
+     * 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.
+     */
+    pollIntervalMs?: number | null;
+    /**
+     * Render a custom placeholder while waiting for scan / upload. Defaults
+     * to a tiny "Loading…" div. Receives the current FileStatus (or null).
+     */
+    renderPlaceholder?: () => React.ReactNode;
+    /**
+     * Render the "blocked" UI when scan flips to `threat`. Defaults to a
+     * "This file was blocked" message. Customize for branding.
+     */
+    renderBlocked?: () => React.ReactNode;
+    /**
+     * Custom render override. If provided, the component still calls
+     * `useFileStatus` but yields rendering to this function. Useful for
+     * highly custom presentation (e.g. lightbox triggers, hover overlays).
+     */
+    renderOverride?: (args: {
+        src: string | null;
+        state: 'preview' | 'pending' | 'ready' | 'blocked' | 'error';
+    }) => React.ReactNode;
+}
+/**
+ * Progressive-enhancement media renderer.
+ *
+ * Renders the right element for the given MIME type and progressively
+ * upgrades the source URL as the media pipeline advances:
+ *
+ *   blob preview (if set) → original view URL → optimized variant (image)
+ *                                            → HLS playlist (video)
+ *
+ * Today this is pull-only — `useFileStatus` polls until scan is clean
+ * (and the caller can stop polling by passing `pollIntervalMs={null}`).
+ * The push variant rides on the chat translation bridge (Phase 3 / P5')
+ * and lights up automatically once that ships.
+ *
+ * For non-Safari browsers, HLS playback requires `hls.js` to be
+ * available. The component dynamic-imports it on first need; if the
+ * import fails (not installed), it falls back to the original-bytes URL.
+ *
+ * @example
+ * ```tsx
+ * <ScaleMuleMedia
+ *   fileId={attachment.file_id}
+ *   mimeType={attachment.mime_type}
+ *   width={520}
+ *   blobPreview={pendingPreviewUrl}
+ *   alt={attachment.filename}
+ * />
+ * ```
+ */
+declare function ScaleMuleMedia(props: ScaleMuleMediaProps): React.ReactElement | null;
+
 declare const useMoney: typeof useMoneyClient;
 
 /**
@@ -815,4 +926,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 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, 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,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { MoneyClient } from '@scalemule/money';
 export { MoneyClient, MoneyClientConfig, createMoneyClient } from '@scalemule/money';
@@ -184,12 +185,43 @@ interface MediaUploadResult {
     /** Whether the resulting storage object is public-readable. */
     is_public: boolean;
 }
+/**
+ * Per-app media-pipeline policy. Drives release-gating + processing
+ * behavior. **Orthogonal to `is_public`.** See
+ * `docs/MEDIA-UPLOADS.md` and ADR-2026-04-26 for the full taxonomy.
+ *
+ * Today's behavior (Phase 4 v1):
+ *   - `fast_trusted` / `safe_visible` (default): upload promise resolves
+ *     as soon as the file is uploaded + registered. The post-processing
+ *     (scan, optimize, transcode) runs async; callers can observe via
+ *     `useFileStatus`.
+ *   - `safe_public` / `moderated`: upload promise *waits* for the
+ *     optimized image variant (image MIME) or HLS playlist (video MIME)
+ *     to become ready before resolving. Acts as the release-gate for
+ *     UGC-style apps that should not publish raw bytes.
+ *   - `compliance`: today behaves as `safe_public`; Phase 4+ adds the
+ *     audit-log + signed-with-purpose URL semantics.
+ */
+type MediaPolicy = 'fast_trusted' | 'safe_visible' | 'safe_public' | 'moderated' | 'compliance';
 interface UseMediaUploadOptions {
     /** Whether the resulting storage object should be public-readable.
      * Default: `false` (private). Public is opt-in for surfaces that
      * genuinely need it (avatars, public listings). Chat / DM uploads
      * should always be private. */
     is_public?: boolean;
+    /**
+     * Per-call media-policy override. Defaults to `safe_visible` (visible
+     * immediately at original fidelity; optimized variants swap in async).
+     * Set to `safe_public` to make the upload promise *await* the optimized
+     * variant (image) or HLS playlist (video) before resolving — useful for
+     * broadcast / UGC apps that gate publication on processing complete.
+     *
+     * The per-app default lives in `application_storage_settings.media_policy`
+     * (Phase 4 / P3, live in prod 2026-04-26). Reading the per-app default
+     * into `useMedia` defaults lands in a follow-up; today the option is
+     * caller-provided per call.
+     */
+    policy?: MediaPolicy;
     /** Display filename (sanitized server-side). */
     filename?: string;
     /** Custom metadata attached to the file. */
@@ -332,6 +364,85 @@ interface UseFileStatusReturn {
  */
 declare function useFileStatus(options: UseFileStatusOptions): UseFileStatusReturn;
 
+interface ScaleMuleMediaProps {
+    /** Storage `file_id` of the media to render. Required. */
+    fileId: string;
+    /** MIME type — drives which element to render. Required. */
+    mimeType: string;
+    /**
+     * Optional sender-side optimistic preview. While the upload is in
+     * progress (or the recipient hasn't yet observed the message), the
+     * component renders this Blob URL. Once `useFileStatus` resolves a
+     * scan-clean state and a server-side URL, the component swaps to it.
+     */
+    blobPreview?: string;
+    /** Display width hint (CSS pixels). Used for image breakpoint selection. */
+    width?: number;
+    /** Display height hint (CSS pixels). */
+    height?: number;
+    /** Pass-through className for the rendered element. */
+    className?: string;
+    /** Pass-through style. */
+    style?: React.CSSProperties;
+    /** Alt text for `<img>`; aria-label for `<audio>` / `<video>`. */
+    alt?: string;
+    /**
+     * 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.
+     */
+    pollIntervalMs?: number | null;
+    /**
+     * Render a custom placeholder while waiting for scan / upload. Defaults
+     * to a tiny "Loading…" div. Receives the current FileStatus (or null).
+     */
+    renderPlaceholder?: () => React.ReactNode;
+    /**
+     * Render the "blocked" UI when scan flips to `threat`. Defaults to a
+     * "This file was blocked" message. Customize for branding.
+     */
+    renderBlocked?: () => React.ReactNode;
+    /**
+     * Custom render override. If provided, the component still calls
+     * `useFileStatus` but yields rendering to this function. Useful for
+     * highly custom presentation (e.g. lightbox triggers, hover overlays).
+     */
+    renderOverride?: (args: {
+        src: string | null;
+        state: 'preview' | 'pending' | 'ready' | 'blocked' | 'error';
+    }) => React.ReactNode;
+}
+/**
+ * Progressive-enhancement media renderer.
+ *
+ * Renders the right element for the given MIME type and progressively
+ * upgrades the source URL as the media pipeline advances:
+ *
+ *   blob preview (if set) → original view URL → optimized variant (image)
+ *                                            → HLS playlist (video)
+ *
+ * Today this is pull-only — `useFileStatus` polls until scan is clean
+ * (and the caller can stop polling by passing `pollIntervalMs={null}`).
+ * The push variant rides on the chat translation bridge (Phase 3 / P5')
+ * and lights up automatically once that ships.
+ *
+ * For non-Safari browsers, HLS playback requires `hls.js` to be
+ * available. The component dynamic-imports it on first need; if the
+ * import fails (not installed), it falls back to the original-bytes URL.
+ *
+ * @example
+ * ```tsx
+ * <ScaleMuleMedia
+ *   fileId={attachment.file_id}
+ *   mimeType={attachment.mime_type}
+ *   width={520}
+ *   blobPreview={pendingPreviewUrl}
+ *   alt={attachment.filename}
+ * />
+ * ```
+ */
+declare function ScaleMuleMedia(props: ScaleMuleMediaProps): React.ReactElement | null;
+
 declare const useMoney: typeof useMoneyClient;
 
 /**
@@ -815,4 +926,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 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, 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 };