@scalemule/nextjs 0.1.27 → 0.1.28

package/dist/index.d.mts

@@ -219,6 +219,8 @@ interface ScaleMuleContextValue {
     video: VideoService;
     /** Base SDK audio service — exposed for `useMedia()` and `audio.uploadViaStorage()` */
     audio: AudioService;
+    /** Base SDK media facade — shared upload/list/delete surface across apps and scripts. */
+    media: unknown;
     /** Base SDK TTS service — exposed for `useTtsJob()` and direct narration requests */
     tts: TtsService;
     /**

package/dist/index.d.ts

@@ -219,6 +219,8 @@ interface ScaleMuleContextValue {
     video: VideoService;
     /** Base SDK audio service — exposed for `useMedia()` and `audio.uploadViaStorage()` */
     audio: AudioService;
+    /** Base SDK media facade — shared upload/list/delete surface across apps and scripts. */
+    media: unknown;
     /** Base SDK TTS service — exposed for `useTtsJob()` and direct narration requests */
     tts: TtsService;
     /**

package/dist/index.js

@@ -2113,6 +2113,24 @@ var DEFAULT_STALL_TIMEOUT_MS = 45e3;
 var SLOW_NETWORK_STALL_TIMEOUT_MS = 9e4;
 var MULTIPART_THRESHOLD = 8 * 1024 * 1024;
 var MULTIPART_THRESHOLD_SLOW = 4 * 1024 * 1024;
+function buildVisibilityWire(options) {
+  if (!options) return {};
+  if (options.visibility) {
+    return {
+      visibility: options.visibility,
+      // Legacy field for old storage instances that haven't deployed
+      // the tristate handler yet — omit `is_public` for the
+      // `anonymous_visible` case so an old server that doesn't know
+      // the new value at least falls through to its own default
+      // rather than mis-treating it as `app_public`.
+      ...options.visibility === "private" ? { is_public: false } : options.visibility === "app_public" ? { is_public: true } : {}
+    };
+  }
+  if (typeof options.isPublic === "boolean") {
+    return { is_public: options.isPublic };
+  }
+  return {};
+}
 var StorageService = class extends ServiceModule {
   constructor() {
     super(...arguments);
@@ -2194,6 +2212,42 @@ var StorageService = class extends ServiceModule {
     }
     return result;
   }
+  /**
+   * Upload a file as world-readable on the anonymous public CDN.
+   *
+   * Same browser→S3 pipeline as {@link upload}, but pins
+   * `visibility: 'anonymous_visible'` — caller cannot opt out.
+   *
+   * Use this for media meant to render on logged-out marketing
+   * pages, blog posts, embed snippets — anywhere a customer needs
+   * to drop a URL into `<img src>` without an authenticated
+   * session. For everything else (chat attachments, private
+   * uploads, app-internal galleries) prefer {@link upload} or
+   * {@link uploadPrivate}.
+   *
+   * **`cdn_url` may be `null` on the immediate response.** Storage
+   * intentionally withholds the public CDN URL until the AV scan
+   * has flipped to `clean` — exposing the URL pre-scan would let a
+   * customer embed the bytes in a logged-out page before the
+   * platform has verified them. The upload itself succeeds
+   * regardless; consumers should check `result.data.cdn_url` and:
+   *   - if non-null → it's safe to publish
+   *   - if null → poll {@link getFileStatus} on a small backoff
+   *     until `urls.cdn_url` populates (or `scan.status` flips to
+   *     `threat` / `quarantined` / `error` — terminal failure)
+   *
+   * Requires the operator to have provisioned the anonymous
+   * delivery bucket + CDN. When they haven't, the storage service
+   * returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED` (an error
+   * propagated through this helper) — it never silently demotes
+   * to `app_public`.
+   */
+  async uploadAnonymous(file, options) {
+    return this.upload(file, {
+      ...options,
+      visibility: "anonymous_visible"
+    });
+  }
   // --------------------------------------------------------------------------
   // Direct Upload (3-step with retry + stall)
   // --------------------------------------------------------------------------
@@ -2207,7 +2261,7 @@ var StorageService = class extends ServiceModule {
         filename,
         content_type: file.type || "application/octet-stream",
         size_bytes: file.size,
-        is_public: options?.isPublic ?? true,
+        ...buildVisibilityWire(options),
         metadata: options?.metadata
       },
       requestOpts
@@ -2298,6 +2352,13 @@ var StorageService = class extends ServiceModule {
         content_type: d.content_type,
         size_bytes: d.size_bytes,
         url: d.url,
+        // Surface visibility + cdn_url all the way out so callers
+        // can branch on visibility without a follow-up getInfo()
+        // round-trip. Anonymous-visible callers especially need
+        // `cdn_url` here to render the image immediately.
+        visibility: d.visibility,
+        cdn_url: d.cdn_url,
+        is_public: d.visibility ? d.visibility !== "private" : void 0,
         created_at: (/* @__PURE__ */ new Date()).toISOString()
       },
       error: null
@@ -2379,7 +2440,7 @@ var StorageService = class extends ServiceModule {
           filename,
           content_type: file.type || "application/octet-stream",
           size_bytes: file.size,
-          is_public: options?.isPublic ?? true,
+          ...buildVisibilityWire(options),
           metadata: options?.metadata,
           chunk_size: options?.chunkSize,
           ...clientUploadKey ? { client_upload_key: clientUploadKey } : {}
@@ -2657,6 +2718,9 @@ var StorageService = class extends ServiceModule {
         content_type: d.content_type,
         size_bytes: d.size_bytes,
         url: d.url,
+        visibility: d.visibility,
+        cdn_url: d.cdn_url,
+        is_public: d.visibility ? d.visibility !== "private" : void 0,
         created_at: (/* @__PURE__ */ new Date()).toISOString()
       },
       error: null
@@ -2694,7 +2758,7 @@ var StorageService = class extends ServiceModule {
       {
         filename,
         content_type: contentType,
-        is_public: options?.isPublic ?? true,
+        ...buildVisibilityWire(options),
         expires_in: options?.expiresIn ?? 3600,
         size_bytes: options?.sizeBytes,
         metadata: options?.metadata
@@ -2741,7 +2805,16 @@ var StorageService = class extends ServiceModule {
   // --------------------------------------------------------------------------
   // Multipart Public API (for advanced/server-side usage)
   // --------------------------------------------------------------------------
-  /** Start a multipart upload session. */
+  /**
+   * Start a multipart upload session.
+   *
+   * Accepts both the typed `visibility` field (preferred) and the
+   * legacy `is_public` boolean for back-compat. If both are sent the
+   * storage service uses `visibility`. `'anonymous_visible'` requires
+   * the operator to have provisioned the anonymous bucket — the
+   * service returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
+   * otherwise (the SDK never silently demotes).
+   */
   async startMultipartUpload(params, requestOptions) {
     return this.post("/signed-url/multipart/start", params, requestOptions);
   }
@@ -2872,14 +2945,26 @@ var StorageService = class extends ServiceModule {
     return this._get(`/files/${fileId}/view-status`, options);
   }
   /**
-   * Update a file's visibility (public/private).
-   * Only the file owner can toggle this. Changes URL TTL — does not move the S3 object.
-   * Public files get 7-day signed URLs; private files get 1-hour signed URLs.
+   * Update a file's visibility.
+   *
+   * Accepts either:
+   *   - a tri-state {@link Visibility} string (preferred), or
+   *   - a legacy boolean (`true` → `app_public`, `false` → `private`).
+   *
+   * Only the file owner / app member can toggle this. Same-bucket
+   * transitions (`private` ↔ `app_public`) succeed and the service
+   * keeps the legacy `is_public` column in sync via a DB trigger.
+   * Cross-bucket transitions (any flip into or out of
+   * `'anonymous_visible'`) currently return 409
+   * `VISIBILITY_TRANSITION_UNSUPPORTED` — the bytes would need to
+   * move between S3 buckets and that orchestration is not yet
+   * shipped. Re-upload the file with the desired visibility instead.
    */
-  async updateVisibility(fileId, isPublic, options) {
+  async updateVisibility(fileId, visibility, options) {
+    const body = typeof visibility === "boolean" ? { is_public: visibility } : { visibility };
     return this.patch(
       `/files/${fileId}/visibility`,
-      { is_public: isPublic },
+      body,
       options
     );
   }
@@ -2977,6 +3062,7 @@ var StorageService = class extends ServiceModule {
       clearTimeout(timer);
       parentSignalCleanup?.();
       if (!response.ok) {
+        const s3ErrorBody = await response.text().catch(() => "");
         return {
           data: null,
           error: {
@@ -2986,7 +3072,9 @@ var StorageService = class extends ServiceModule {
             details: {
               transport: "fetch",
               total_bytes: file.size,
-              online: getOnlineStatus()
+              online: getOnlineStatus(),
+              s3_error_body: s3ErrorBody.slice(0, 1024),
+              s3_error_code: extractS3ErrorCode(s3ErrorBody)
             }
           }
         };
@@ -3077,6 +3165,7 @@ var StorageService = class extends ServiceModule {
           onProgress?.(100);
           resolve({ data: null, error: null });
         } else {
+          const body = (xhr.responseText || "").slice(0, 1024);
           resolve({
             data: null,
             error: {
@@ -3088,7 +3177,9 @@ var StorageService = class extends ServiceModule {
                 bytes_sent: lastLoaded,
                 total_bytes: totalBytes,
                 progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
-                online: getOnlineStatus()
+                online: getOnlineStatus(),
+                s3_error_body: body,
+                s3_error_code: extractS3ErrorCode(body)
               }
             }
           });
@@ -3167,12 +3258,18 @@ var StorageService = class extends ServiceModule {
           }
           return { etag };
         }
+        const body = await response.text().catch(() => "");
+        const s3ErrorCode = extractS3ErrorCode(body);
         if (NON_RETRYABLE_STATUS_CODES.has(response.status)) {
-          return { error: `Part upload failed: ${response.status}`, status: response.status, code: "s3_error" };
+          return {
+            error: `Part upload failed: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
+            status: response.status,
+            code: response.status === 403 ? "s3_signature_error" : "s3_error"
+          };
         }
         if (attempt === RETRY_DELAYS.length - 1) {
           return {
-            error: `Part upload failed after retries: ${response.status}`,
+            error: `Part upload failed after retries: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
             status: response.status,
             code: "s3_error"
           };
@@ -3298,6 +3395,11 @@ function getUploadEnvironmentDiagnostics() {
 function asNumber2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+function extractS3ErrorCode(body) {
+  if (!body) return void 0;
+  const m = body.match(/<Code>([^<]+)<\/Code>/);
+  return m ? m[1] : void 0;
+}
 var DEFAULT_RECONNECT_BASE_MS = 1e3;
 var MAX_RECONNECT_MS = 3e4;
 var HEARTBEAT_INTERVAL_MS = 3e4;
@@ -4211,6 +4313,56 @@ var SocialService = class extends ServiceModule {
     return this._list(`/${targetType}/${targetId}/likes`, params, requestOptions);
   }
   // --------------------------------------------------------------------------
+  // Voting (bipolar — up/down with score)
+  // --------------------------------------------------------------------------
+  /**
+   * Cast, change, or clear the caller's vote on a target.
+   *
+   * `value`: 1 = upvote, -1 = downvote, 0 = clear.
+   *
+   * Idempotent: re-casting the same value is a no-op; clearing when no
+   * vote exists is a no-op. Server validates `target_type` matches
+   * `[a-z0-9_]{1,64}`. Convention: prefix per app (`weekmob_post`,
+   * `gistyo_gist`).
+   *
+   * Requires an authenticated session; anonymous calls return 401.
+   */
+  async vote(targetType, targetId, value, options) {
+    return this.put(`/${targetType}/${targetId}/vote`, { value }, options);
+  }
+  /**
+   * Read the caller's current vote on a target plus the aggregate counts.
+   * `value` is 0 when the caller has no vote.
+   *
+   * Requires an authenticated session.
+   */
+  async getVote(targetType, targetId, options) {
+    return this._get(`/${targetType}/${targetId}/vote`, options);
+  }
+  // --------------------------------------------------------------------------
+  // View counters
+  // --------------------------------------------------------------------------
+  /**
+   * Record a view of a target. Increments the total counter
+   * unconditionally; increments the unique-viewer counter once per
+   * (viewer, UTC day).
+   *
+   * Authenticated callers don't need to pass `viewerFingerprint` — the
+   * user_id is used. Anonymous callers may pass a 64-hex-char
+   * fingerprint hash to participate in unique-viewer dedupe; without
+   * one, only the total counter moves.
+   */
+  async recordView(targetType, targetId, viewerFingerprint, options) {
+    const body = viewerFingerprint ? { viewer_fingerprint: viewerFingerprint } : {};
+    return this.post(`/${targetType}/${targetId}/views`, body, options);
+  }
+  /**
+   * Read view counters for a target.
+   */
+  async getViews(targetType, targetId, options) {
+    return this._get(`/${targetType}/${targetId}/views`, options);
+  }
+  // --------------------------------------------------------------------------
   // Comments
   // --------------------------------------------------------------------------
   async comment(postId, data, options) {
@@ -5571,6 +5723,41 @@ var PhotoService = class extends ServiceModule {
     const qs = params.toString();
     return `${this.client.getBaseUrl()}${this.basePath}/${photoId}/transform${qs ? `?${qs}` : ""}`;
   }
+  /**
+   * Build an absolute URL for the **public** transform endpoint —
+   * the unauthenticated path that serves transformed bytes for
+   * `<img src>` use on logged-out marketing pages, blogs, embeds.
+   *
+   * The photo service refuses any photo that isn't:
+   *   - `visibility = 'anonymous_visible'` (the customer explicitly
+   *     opted into world-readable for this file at upload time)
+   *   - `scan_status = 'clean'` (no exception for pending/scanning)
+   *
+   * Anything else returns 404 — the endpoint refuses to disambiguate
+   * "not found" from "not anonymous" so it can't be probed to
+   * discover existence or visibility of private photos.
+   *
+   * Pair with {@link getTransformUrl} for the authenticated case:
+   * customer apps that already have a session should keep using the
+   * authed transform URL (which also handles `anonymous_visible`
+   * photos transparently) — this URL is for cross-origin embedding.
+   *
+   * @example
+   * ```tsx
+   * // photo was uploaded with visibility: 'anonymous_visible'
+   * <img src={sm.photo.getPublicTransformUrl(photoId, { width: 800 })} />
+   * ```
+   */
+  getPublicTransformUrl(photoId, options) {
+    const params = new URLSearchParams();
+    if (options?.width) params.set("width", String(options.width));
+    if (options?.height) params.set("height", String(options.height));
+    if (options?.fit) params.set("fit", options.fit);
+    if (options?.format) params.set("format", options.format);
+    if (options?.quality) params.set("quality", String(options.quality));
+    const qs = params.toString();
+    return `${this.client.getBaseUrl()}${this.basePath}/public/${photoId}/transform${qs ? `?${qs}` : ""}`;
+  }
   /**
    * Get a transform URL optimized for the given display area.
    *
@@ -5843,6 +6030,7 @@ var TtsService = class extends ServiceModule {
       "/synthesize",
       {
         text: params.text,
+        speech_profile: params.speechProfile,
         voice: params.voice,
         model: params.model,
         provider: params.provider,
@@ -7976,6 +8164,7 @@ function ScaleMuleProvider({
       photo: baseClient.photo,
       video: baseClient.video,
       audio: baseClient.audio,
+      media: baseClient.media,
       tts: baseClient.tts,
       mediaPolicy: effectiveMediaPolicy,
       user,
@@ -9537,148 +9726,43 @@ function useTtsJob(jobId, options) {
   return { job, loading, error, refresh };
 }
 function useMedia() {
-  const { storage, photo, video, audio, mediaPolicy: providerDefaultPolicy } = useScaleMule();
+  const { media: rawMedia, mediaPolicy: providerDefaultPolicy } = useScaleMule();
+  const media = rawMedia;
   const [uploading, setUploading] = React.useState(false);
   const [error, setError] = React.useState(null);
   const upload = React.useCallback(
     async (file, options) => {
       setUploading(true);
       setError(null);
-      const visibility = options?.visibility ?? (options?.is_public === true ? "app_public" : options?.is_public === false ? "private" : "private");
-      const isPublic = visibility !== "private";
-      const isAnonymous = visibility === "anonymous_visible";
-      const mimeType = file.type || "application/octet-stream";
       const policy = options?.policy ?? providerDefaultPolicy ?? "safe_visible";
-      const gateOnPipeline = policy === "safe_public" || policy === "moderated" || policy === "compliance";
-      const sharedOpts = {
-        filename: options?.filename,
-        metadata: options?.metadata,
-        onProgress: options?.onProgress,
-        signal: options?.signal
-      };
-      const storageAnon = storage;
       try {
-        if (isAnonymous) {
-          const r2 = await storageAnon.uploadAnonymous(file, sharedOpts);
-          if (r2.error || !r2.data) {
-            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
-          }
-          const f2 = r2.data;
-          return {
-            file_id: f2.id,
-            photo_id: null,
-            // For anon files, original_view_url is the same unsigned
-            // CDN URL — no signed alternative exists. Callers should
-            // prefer `cdn_url` (more specific) but `original_view_url`
-            // works too for back-compat with code that already reads
-            // that field.
-            original_view_url: f2.cdn_url ?? null,
-            optimized_url_promise: Promise.resolve(null),
-            hls_url_promise: Promise.resolve(null),
-            mime_type: mimeType,
-            is_public: true,
-            visibility: "anonymous_visible",
-            cdn_url: f2.cdn_url ?? null
-          };
-        }
-        if (mimeType.startsWith("image/") && !options?.skipPhotoRegister && !isPublic) {
-          const r2 = await photo.uploadViaStorage(file, sharedOpts);
-          if (r2.error || !r2.data) {
-            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
-          }
-          if (gateOnPipeline) {
-            await r2.data.optimized_url_promise;
-          }
-          return {
-            file_id: r2.data.file_id,
-            photo_id: r2.data.photo_id,
-            original_view_url: r2.data.original_view_url,
-            optimized_url_promise: r2.data.optimized_url_promise,
-            hls_url_promise: Promise.resolve(null),
-            mime_type: mimeType,
-            is_public: false,
-            visibility: "private",
-            cdn_url: null
-          };
-        }
-        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 };
-          }
-          if (gateOnPipeline) {
-            await r2.data.hls_url_promise;
-          }
-          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,
-            visibility: "private",
-            cdn_url: null
-          };
-        }
-        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,
-            visibility: "private",
-            cdn_url: null
-          };
-        }
-        if (mimeType.startsWith("image/") && isPublic) {
-          const r2 = await storage.upload(file, {
-            ...sharedOpts,
-            visibility: "app_public",
-            skipCompression: true
-          });
-          if (r2.error || !r2.data) {
-            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
+        const result = await media.upload(file, {
+          visibility: options?.visibility,
+          isPublic: options?.is_public,
+          policy,
+          filename: options?.filename,
+          metadata: options?.metadata,
+          signal: options?.signal,
+          skipPhotoRegister: options?.skipPhotoRegister,
+          onProgress: (event) => {
+            if (typeof event.progress === "number") {
+              options?.onProgress?.(event.progress);
+            }
           }
-          const f2 = r2.data;
-          return {
-            file_id: f2.id,
-            photo_id: null,
-            original_view_url: f2.url ?? null,
-            optimized_url_promise: Promise.resolve(null),
-            hls_url_promise: Promise.resolve(null),
-            mime_type: mimeType,
-            is_public: f2.is_public ?? true,
-            visibility: f2.visibility ?? "app_public",
-            cdn_url: f2.cdn_url ?? null
-          };
-        }
-        const r = isPublic ? await storage.upload(file, {
-          ...sharedOpts,
-          visibility: "app_public",
-          skipCompression: true
-        }) : await storage.uploadPrivate(file, sharedOpts);
-        if (r.error || !r.data) {
-          throw r.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
+        });
+        if (result.error || !result.data) {
+          throw result.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
         }
-        const f = r.data;
         return {
-          file_id: f.id,
-          photo_id: null,
-          original_view_url: f.url ?? null,
-          optimized_url_promise: Promise.resolve(null),
-          hls_url_promise: Promise.resolve(null),
-          mime_type: mimeType,
-          is_public: f.is_public ?? isPublic,
-          visibility: f.visibility ?? (isPublic ? "app_public" : "private"),
-          cdn_url: f.cdn_url ?? null
+          file_id: result.data.file_id,
+          photo_id: result.data.photo_id,
+          original_view_url: result.data.original_view_url,
+          optimized_url_promise: result.data.optimized_url_promise,
+          hls_url_promise: result.data.hls_url_promise,
+          mime_type: result.data.mime_type,
+          is_public: result.data.is_public,
+          visibility: result.data.visibility,
+          cdn_url: result.data.cdn_url
         };
       } catch (err) {
         const e = err;
@@ -9688,19 +9772,16 @@ function useMedia() {
         setUploading(false);
       }
     },
-    [storage, photo, video, audio, providerDefaultPolicy]
+    [media, providerDefaultPolicy]
   );
   const cancelUpload = React.useCallback(
     async (fileId) => {
       setError(null);
       try {
-        const [, storageResult] = await Promise.all([
-          photo.delete(fileId).catch(() => void 0),
-          storage.delete(fileId)
-        ]);
-        if (storageResult.error) {
-          if (storageResult.error.status === 404) return;
-          throw storageResult.error;
+        const result = await media.delete(fileId);
+        if (result.error) {
+          if (result.error.status === 404) return;
+          throw result.error;
         }
       } catch (err) {
         const e = err;
@@ -9708,7 +9789,7 @@ function useMedia() {
         throw e;
       }
     },
-    [storage, photo]
+    [media]
   );
   return { upload, cancelUpload, error, uploading };
 }

package/dist/index.mjs

@@ -2093,6 +2093,24 @@ var DEFAULT_STALL_TIMEOUT_MS = 45e3;
 var SLOW_NETWORK_STALL_TIMEOUT_MS = 9e4;
 var MULTIPART_THRESHOLD = 8 * 1024 * 1024;
 var MULTIPART_THRESHOLD_SLOW = 4 * 1024 * 1024;
+function buildVisibilityWire(options) {
+  if (!options) return {};
+  if (options.visibility) {
+    return {
+      visibility: options.visibility,
+      // Legacy field for old storage instances that haven't deployed
+      // the tristate handler yet — omit `is_public` for the
+      // `anonymous_visible` case so an old server that doesn't know
+      // the new value at least falls through to its own default
+      // rather than mis-treating it as `app_public`.
+      ...options.visibility === "private" ? { is_public: false } : options.visibility === "app_public" ? { is_public: true } : {}
+    };
+  }
+  if (typeof options.isPublic === "boolean") {
+    return { is_public: options.isPublic };
+  }
+  return {};
+}
 var StorageService = class extends ServiceModule {
   constructor() {
     super(...arguments);
@@ -2174,6 +2192,42 @@ var StorageService = class extends ServiceModule {
     }
     return result;
   }
+  /**
+   * Upload a file as world-readable on the anonymous public CDN.
+   *
+   * Same browser→S3 pipeline as {@link upload}, but pins
+   * `visibility: 'anonymous_visible'` — caller cannot opt out.
+   *
+   * Use this for media meant to render on logged-out marketing
+   * pages, blog posts, embed snippets — anywhere a customer needs
+   * to drop a URL into `<img src>` without an authenticated
+   * session. For everything else (chat attachments, private
+   * uploads, app-internal galleries) prefer {@link upload} or
+   * {@link uploadPrivate}.
+   *
+   * **`cdn_url` may be `null` on the immediate response.** Storage
+   * intentionally withholds the public CDN URL until the AV scan
+   * has flipped to `clean` — exposing the URL pre-scan would let a
+   * customer embed the bytes in a logged-out page before the
+   * platform has verified them. The upload itself succeeds
+   * regardless; consumers should check `result.data.cdn_url` and:
+   *   - if non-null → it's safe to publish
+   *   - if null → poll {@link getFileStatus} on a small backoff
+   *     until `urls.cdn_url` populates (or `scan.status` flips to
+   *     `threat` / `quarantined` / `error` — terminal failure)
+   *
+   * Requires the operator to have provisioned the anonymous
+   * delivery bucket + CDN. When they haven't, the storage service
+   * returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED` (an error
+   * propagated through this helper) — it never silently demotes
+   * to `app_public`.
+   */
+  async uploadAnonymous(file, options) {
+    return this.upload(file, {
+      ...options,
+      visibility: "anonymous_visible"
+    });
+  }
   // --------------------------------------------------------------------------
   // Direct Upload (3-step with retry + stall)
   // --------------------------------------------------------------------------
@@ -2187,7 +2241,7 @@ var StorageService = class extends ServiceModule {
         filename,
         content_type: file.type || "application/octet-stream",
         size_bytes: file.size,
-        is_public: options?.isPublic ?? true,
+        ...buildVisibilityWire(options),
         metadata: options?.metadata
       },
       requestOpts
@@ -2278,6 +2332,13 @@ var StorageService = class extends ServiceModule {
         content_type: d.content_type,
         size_bytes: d.size_bytes,
         url: d.url,
+        // Surface visibility + cdn_url all the way out so callers
+        // can branch on visibility without a follow-up getInfo()
+        // round-trip. Anonymous-visible callers especially need
+        // `cdn_url` here to render the image immediately.
+        visibility: d.visibility,
+        cdn_url: d.cdn_url,
+        is_public: d.visibility ? d.visibility !== "private" : void 0,
         created_at: (/* @__PURE__ */ new Date()).toISOString()
       },
       error: null
@@ -2359,7 +2420,7 @@ var StorageService = class extends ServiceModule {
           filename,
           content_type: file.type || "application/octet-stream",
           size_bytes: file.size,
-          is_public: options?.isPublic ?? true,
+          ...buildVisibilityWire(options),
           metadata: options?.metadata,
           chunk_size: options?.chunkSize,
           ...clientUploadKey ? { client_upload_key: clientUploadKey } : {}
@@ -2637,6 +2698,9 @@ var StorageService = class extends ServiceModule {
         content_type: d.content_type,
         size_bytes: d.size_bytes,
         url: d.url,
+        visibility: d.visibility,
+        cdn_url: d.cdn_url,
+        is_public: d.visibility ? d.visibility !== "private" : void 0,
         created_at: (/* @__PURE__ */ new Date()).toISOString()
       },
       error: null
@@ -2674,7 +2738,7 @@ var StorageService = class extends ServiceModule {
       {
         filename,
         content_type: contentType,
-        is_public: options?.isPublic ?? true,
+        ...buildVisibilityWire(options),
         expires_in: options?.expiresIn ?? 3600,
         size_bytes: options?.sizeBytes,
         metadata: options?.metadata
@@ -2721,7 +2785,16 @@ var StorageService = class extends ServiceModule {
   // --------------------------------------------------------------------------
   // Multipart Public API (for advanced/server-side usage)
   // --------------------------------------------------------------------------
-  /** Start a multipart upload session. */
+  /**
+   * Start a multipart upload session.
+   *
+   * Accepts both the typed `visibility` field (preferred) and the
+   * legacy `is_public` boolean for back-compat. If both are sent the
+   * storage service uses `visibility`. `'anonymous_visible'` requires
+   * the operator to have provisioned the anonymous bucket — the
+   * service returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
+   * otherwise (the SDK never silently demotes).
+   */
   async startMultipartUpload(params, requestOptions) {
     return this.post("/signed-url/multipart/start", params, requestOptions);
   }
@@ -2852,14 +2925,26 @@ var StorageService = class extends ServiceModule {
     return this._get(`/files/${fileId}/view-status`, options);
   }
   /**
-   * Update a file's visibility (public/private).
-   * Only the file owner can toggle this. Changes URL TTL — does not move the S3 object.
-   * Public files get 7-day signed URLs; private files get 1-hour signed URLs.
+   * Update a file's visibility.
+   *
+   * Accepts either:
+   *   - a tri-state {@link Visibility} string (preferred), or
+   *   - a legacy boolean (`true` → `app_public`, `false` → `private`).
+   *
+   * Only the file owner / app member can toggle this. Same-bucket
+   * transitions (`private` ↔ `app_public`) succeed and the service
+   * keeps the legacy `is_public` column in sync via a DB trigger.
+   * Cross-bucket transitions (any flip into or out of
+   * `'anonymous_visible'`) currently return 409
+   * `VISIBILITY_TRANSITION_UNSUPPORTED` — the bytes would need to
+   * move between S3 buckets and that orchestration is not yet
+   * shipped. Re-upload the file with the desired visibility instead.
    */
-  async updateVisibility(fileId, isPublic, options) {
+  async updateVisibility(fileId, visibility, options) {
+    const body = typeof visibility === "boolean" ? { is_public: visibility } : { visibility };
     return this.patch(
       `/files/${fileId}/visibility`,
-      { is_public: isPublic },
+      body,
       options
     );
   }
@@ -2957,6 +3042,7 @@ var StorageService = class extends ServiceModule {
       clearTimeout(timer);
       parentSignalCleanup?.();
       if (!response.ok) {
+        const s3ErrorBody = await response.text().catch(() => "");
         return {
           data: null,
           error: {
@@ -2966,7 +3052,9 @@ var StorageService = class extends ServiceModule {
             details: {
               transport: "fetch",
               total_bytes: file.size,
-              online: getOnlineStatus()
+              online: getOnlineStatus(),
+              s3_error_body: s3ErrorBody.slice(0, 1024),
+              s3_error_code: extractS3ErrorCode(s3ErrorBody)
             }
           }
         };
@@ -3057,6 +3145,7 @@ var StorageService = class extends ServiceModule {
           onProgress?.(100);
           resolve({ data: null, error: null });
         } else {
+          const body = (xhr.responseText || "").slice(0, 1024);
           resolve({
             data: null,
             error: {
@@ -3068,7 +3157,9 @@ var StorageService = class extends ServiceModule {
                 bytes_sent: lastLoaded,
                 total_bytes: totalBytes,
                 progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
-                online: getOnlineStatus()
+                online: getOnlineStatus(),
+                s3_error_body: body,
+                s3_error_code: extractS3ErrorCode(body)
               }
             }
           });
@@ -3147,12 +3238,18 @@ var StorageService = class extends ServiceModule {
           }
           return { etag };
         }
+        const body = await response.text().catch(() => "");
+        const s3ErrorCode = extractS3ErrorCode(body);
         if (NON_RETRYABLE_STATUS_CODES.has(response.status)) {
-          return { error: `Part upload failed: ${response.status}`, status: response.status, code: "s3_error" };
+          return {
+            error: `Part upload failed: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
+            status: response.status,
+            code: response.status === 403 ? "s3_signature_error" : "s3_error"
+          };
         }
         if (attempt === RETRY_DELAYS.length - 1) {
           return {
-            error: `Part upload failed after retries: ${response.status}`,
+            error: `Part upload failed after retries: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
             status: response.status,
             code: "s3_error"
           };
@@ -3278,6 +3375,11 @@ function getUploadEnvironmentDiagnostics() {
 function asNumber2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+function extractS3ErrorCode(body) {
+  if (!body) return void 0;
+  const m = body.match(/<Code>([^<]+)<\/Code>/);
+  return m ? m[1] : void 0;
+}
 var DEFAULT_RECONNECT_BASE_MS = 1e3;
 var MAX_RECONNECT_MS = 3e4;
 var HEARTBEAT_INTERVAL_MS = 3e4;
@@ -4191,6 +4293,56 @@ var SocialService = class extends ServiceModule {
     return this._list(`/${targetType}/${targetId}/likes`, params, requestOptions);
   }
   // --------------------------------------------------------------------------
+  // Voting (bipolar — up/down with score)
+  // --------------------------------------------------------------------------
+  /**
+   * Cast, change, or clear the caller's vote on a target.
+   *
+   * `value`: 1 = upvote, -1 = downvote, 0 = clear.
+   *
+   * Idempotent: re-casting the same value is a no-op; clearing when no
+   * vote exists is a no-op. Server validates `target_type` matches
+   * `[a-z0-9_]{1,64}`. Convention: prefix per app (`weekmob_post`,
+   * `gistyo_gist`).
+   *
+   * Requires an authenticated session; anonymous calls return 401.
+   */
+  async vote(targetType, targetId, value, options) {
+    return this.put(`/${targetType}/${targetId}/vote`, { value }, options);
+  }
+  /**
+   * Read the caller's current vote on a target plus the aggregate counts.
+   * `value` is 0 when the caller has no vote.
+   *
+   * Requires an authenticated session.
+   */
+  async getVote(targetType, targetId, options) {
+    return this._get(`/${targetType}/${targetId}/vote`, options);
+  }
+  // --------------------------------------------------------------------------
+  // View counters
+  // --------------------------------------------------------------------------
+  /**
+   * Record a view of a target. Increments the total counter
+   * unconditionally; increments the unique-viewer counter once per
+   * (viewer, UTC day).
+   *
+   * Authenticated callers don't need to pass `viewerFingerprint` — the
+   * user_id is used. Anonymous callers may pass a 64-hex-char
+   * fingerprint hash to participate in unique-viewer dedupe; without
+   * one, only the total counter moves.
+   */
+  async recordView(targetType, targetId, viewerFingerprint, options) {
+    const body = viewerFingerprint ? { viewer_fingerprint: viewerFingerprint } : {};
+    return this.post(`/${targetType}/${targetId}/views`, body, options);
+  }
+  /**
+   * Read view counters for a target.
+   */
+  async getViews(targetType, targetId, options) {
+    return this._get(`/${targetType}/${targetId}/views`, options);
+  }
+  // --------------------------------------------------------------------------
   // Comments
   // --------------------------------------------------------------------------
   async comment(postId, data, options) {
@@ -5551,6 +5703,41 @@ var PhotoService = class extends ServiceModule {
     const qs = params.toString();
     return `${this.client.getBaseUrl()}${this.basePath}/${photoId}/transform${qs ? `?${qs}` : ""}`;
   }
+  /**
+   * Build an absolute URL for the **public** transform endpoint —
+   * the unauthenticated path that serves transformed bytes for
+   * `<img src>` use on logged-out marketing pages, blogs, embeds.
+   *
+   * The photo service refuses any photo that isn't:
+   *   - `visibility = 'anonymous_visible'` (the customer explicitly
+   *     opted into world-readable for this file at upload time)
+   *   - `scan_status = 'clean'` (no exception for pending/scanning)
+   *
+   * Anything else returns 404 — the endpoint refuses to disambiguate
+   * "not found" from "not anonymous" so it can't be probed to
+   * discover existence or visibility of private photos.
+   *
+   * Pair with {@link getTransformUrl} for the authenticated case:
+   * customer apps that already have a session should keep using the
+   * authed transform URL (which also handles `anonymous_visible`
+   * photos transparently) — this URL is for cross-origin embedding.
+   *
+   * @example
+   * ```tsx
+   * // photo was uploaded with visibility: 'anonymous_visible'
+   * <img src={sm.photo.getPublicTransformUrl(photoId, { width: 800 })} />
+   * ```
+   */
+  getPublicTransformUrl(photoId, options) {
+    const params = new URLSearchParams();
+    if (options?.width) params.set("width", String(options.width));
+    if (options?.height) params.set("height", String(options.height));
+    if (options?.fit) params.set("fit", options.fit);
+    if (options?.format) params.set("format", options.format);
+    if (options?.quality) params.set("quality", String(options.quality));
+    const qs = params.toString();
+    return `${this.client.getBaseUrl()}${this.basePath}/public/${photoId}/transform${qs ? `?${qs}` : ""}`;
+  }
   /**
    * Get a transform URL optimized for the given display area.
    *
@@ -5823,6 +6010,7 @@ var TtsService = class extends ServiceModule {
       "/synthesize",
       {
         text: params.text,
+        speech_profile: params.speechProfile,
         voice: params.voice,
         model: params.model,
         provider: params.provider,
@@ -7956,6 +8144,7 @@ function ScaleMuleProvider({
       photo: baseClient.photo,
       video: baseClient.video,
       audio: baseClient.audio,
+      media: baseClient.media,
       tts: baseClient.tts,
       mediaPolicy: effectiveMediaPolicy,
       user,
@@ -9517,148 +9706,43 @@ function useTtsJob(jobId, options) {
   return { job, loading, error, refresh };
 }
 function useMedia() {
-  const { storage, photo, video, audio, mediaPolicy: providerDefaultPolicy } = useScaleMule();
+  const { media: rawMedia, mediaPolicy: providerDefaultPolicy } = useScaleMule();
+  const media = rawMedia;
   const [uploading, setUploading] = useState(false);
   const [error, setError] = useState(null);
   const upload = useCallback(
     async (file, options) => {
       setUploading(true);
       setError(null);
-      const visibility = options?.visibility ?? (options?.is_public === true ? "app_public" : options?.is_public === false ? "private" : "private");
-      const isPublic = visibility !== "private";
-      const isAnonymous = visibility === "anonymous_visible";
-      const mimeType = file.type || "application/octet-stream";
       const policy = options?.policy ?? providerDefaultPolicy ?? "safe_visible";
-      const gateOnPipeline = policy === "safe_public" || policy === "moderated" || policy === "compliance";
-      const sharedOpts = {
-        filename: options?.filename,
-        metadata: options?.metadata,
-        onProgress: options?.onProgress,
-        signal: options?.signal
-      };
-      const storageAnon = storage;
       try {
-        if (isAnonymous) {
-          const r2 = await storageAnon.uploadAnonymous(file, sharedOpts);
-          if (r2.error || !r2.data) {
-            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
-          }
-          const f2 = r2.data;
-          return {
-            file_id: f2.id,
-            photo_id: null,
-            // For anon files, original_view_url is the same unsigned
-            // CDN URL — no signed alternative exists. Callers should
-            // prefer `cdn_url` (more specific) but `original_view_url`
-            // works too for back-compat with code that already reads
-            // that field.
-            original_view_url: f2.cdn_url ?? null,
-            optimized_url_promise: Promise.resolve(null),
-            hls_url_promise: Promise.resolve(null),
-            mime_type: mimeType,
-            is_public: true,
-            visibility: "anonymous_visible",
-            cdn_url: f2.cdn_url ?? null
-          };
-        }
-        if (mimeType.startsWith("image/") && !options?.skipPhotoRegister && !isPublic) {
-          const r2 = await photo.uploadViaStorage(file, sharedOpts);
-          if (r2.error || !r2.data) {
-            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
-          }
-          if (gateOnPipeline) {
-            await r2.data.optimized_url_promise;
-          }
-          return {
-            file_id: r2.data.file_id,
-            photo_id: r2.data.photo_id,
-            original_view_url: r2.data.original_view_url,
-            optimized_url_promise: r2.data.optimized_url_promise,
-            hls_url_promise: Promise.resolve(null),
-            mime_type: mimeType,
-            is_public: false,
-            visibility: "private",
-            cdn_url: null
-          };
-        }
-        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 };
-          }
-          if (gateOnPipeline) {
-            await r2.data.hls_url_promise;
-          }
-          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,
-            visibility: "private",
-            cdn_url: null
-          };
-        }
-        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,
-            visibility: "private",
-            cdn_url: null
-          };
-        }
-        if (mimeType.startsWith("image/") && isPublic) {
-          const r2 = await storage.upload(file, {
-            ...sharedOpts,
-            visibility: "app_public",
-            skipCompression: true
-          });
-          if (r2.error || !r2.data) {
-            throw r2.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
+        const result = await media.upload(file, {
+          visibility: options?.visibility,
+          isPublic: options?.is_public,
+          policy,
+          filename: options?.filename,
+          metadata: options?.metadata,
+          signal: options?.signal,
+          skipPhotoRegister: options?.skipPhotoRegister,
+          onProgress: (event) => {
+            if (typeof event.progress === "number") {
+              options?.onProgress?.(event.progress);
+            }
           }
-          const f2 = r2.data;
-          return {
-            file_id: f2.id,
-            photo_id: null,
-            original_view_url: f2.url ?? null,
-            optimized_url_promise: Promise.resolve(null),
-            hls_url_promise: Promise.resolve(null),
-            mime_type: mimeType,
-            is_public: f2.is_public ?? true,
-            visibility: f2.visibility ?? "app_public",
-            cdn_url: f2.cdn_url ?? null
-          };
-        }
-        const r = isPublic ? await storage.upload(file, {
-          ...sharedOpts,
-          visibility: "app_public",
-          skipCompression: true
-        }) : await storage.uploadPrivate(file, sharedOpts);
-        if (r.error || !r.data) {
-          throw r.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
+        });
+        if (result.error || !result.data) {
+          throw result.error ?? { code: "upload_error", message: "Upload failed", status: 0 };
         }
-        const f = r.data;
         return {
-          file_id: f.id,
-          photo_id: null,
-          original_view_url: f.url ?? null,
-          optimized_url_promise: Promise.resolve(null),
-          hls_url_promise: Promise.resolve(null),
-          mime_type: mimeType,
-          is_public: f.is_public ?? isPublic,
-          visibility: f.visibility ?? (isPublic ? "app_public" : "private"),
-          cdn_url: f.cdn_url ?? null
+          file_id: result.data.file_id,
+          photo_id: result.data.photo_id,
+          original_view_url: result.data.original_view_url,
+          optimized_url_promise: result.data.optimized_url_promise,
+          hls_url_promise: result.data.hls_url_promise,
+          mime_type: result.data.mime_type,
+          is_public: result.data.is_public,
+          visibility: result.data.visibility,
+          cdn_url: result.data.cdn_url
         };
       } catch (err) {
         const e = err;
@@ -9668,19 +9752,16 @@ function useMedia() {
         setUploading(false);
       }
     },
-    [storage, photo, video, audio, providerDefaultPolicy]
+    [media, providerDefaultPolicy]
   );
   const cancelUpload = useCallback(
     async (fileId) => {
       setError(null);
       try {
-        const [, storageResult] = await Promise.all([
-          photo.delete(fileId).catch(() => void 0),
-          storage.delete(fileId)
-        ]);
-        if (storageResult.error) {
-          if (storageResult.error.status === 404) return;
-          throw storageResult.error;
+        const result = await media.delete(fileId);
+        if (result.error) {
+          if (result.error.status === 404) return;
+          throw result.error;
         }
       } catch (err) {
         const e = err;
@@ -9688,7 +9769,7 @@ function useMedia() {
         throw e;
       }
     },
-    [storage, photo]
+    [media]
   );
   return { upload, cancelUpload, error, uploading };
 }

package/package.json

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