@scalemule/sdk 0.0.43 → 0.0.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +49 -3
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -149,8 +149,46 @@ if (!normalized.valid) {
149
149
  }
150
150
  ```
151
151
 
152
+ ## Media uploads (recommended for image / video / audio)
153
+
154
+ Typed services upload directly to S3 (no body-size traps), register with the
155
+ photo / video / audio service in the background, and return URLs that
156
+ progressively enhance as the optimize / transcode workers finish.
157
+
158
+ ```ts
159
+ // Image — uploads private, registers for optimization, returns transform URL
160
+ const { data: photo } = await sm.photo.uploadViaStorage(file)
161
+ // photo: { file_id, original_view_url, optimized_url_promise }
162
+
163
+ // Video — uploads private, registers for HLS transcoding
164
+ const { data: video } = await sm.video.uploadViaStorage(file)
165
+ // video: { file_id, original_view_url, hls_url_promise }
166
+
167
+ // Audio — uploads private + registers metadata. Waveform / transcode are
168
+ // scheduled when the audio service ships its post-processing worker
169
+ // (Phase 3B); until then this returns just the file_id and view URL.
170
+ const { data: audio } = await sm.audio.uploadViaStorage(file)
171
+
172
+ // One-shot status (use this for non-chat surfaces)
173
+ const { data: status } = await sm.storage.getFileStatus(photo!.file_id)
174
+ // { scan, optimize, transcode, urls: { original, optimized?, hls? } }
175
+ ```
176
+
177
+ Every method returns `{ data, error }` — destructure `data` (and check `error`)
178
+ before reaching into the result.
179
+
180
+ For Next.js apps, prefer `useMedia()` from `@scalemule/nextjs` — it routes by
181
+ MIME type and exposes a single hook for chat composers. See
182
+ [`docs/MEDIA-UPLOADS.md`](https://github.com/scalemule/scalemule-repos/blob/main/docs/MEDIA-UPLOADS.md)
183
+ for the decision tree (fast vs safe policy modes, private vs public visibility,
184
+ anti-patterns).
185
+
152
186
  ## Storage
153
187
 
188
+ Use this for plain files that don't need image optimization or video
189
+ transcoding (documents, downloads, exports). For media, prefer the typed
190
+ services above.
191
+
154
192
  ```ts
155
193
  // Upload (3-step presigned URL flow, hidden from you)
156
194
  const { data, error } = await sm.storage.upload(file, {
@@ -160,6 +198,9 @@ const { data, error } = await sm.storage.upload(file, {
160
198
  signal: abortController.signal,
161
199
  })
162
200
 
201
+ // Private upload primitive (no compression, is_public: false enforced)
202
+ const { data } = await sm.storage.uploadPrivate(file)
203
+
163
204
  // Signed URLs for viewing/downloading
164
205
  const { data } = await sm.storage.getViewUrl(fileId)
165
206
  const { data: urls } = await sm.storage.getViewUrls(fileIds) // batch, up to 100
@@ -170,6 +211,9 @@ const { data: info } = await sm.storage.getInfo(fileId)
170
211
  const { data: files, metadata } = await sm.storage.list({ page: 1, perPage: 20 })
171
212
  await sm.storage.delete(fileId)
172
213
 
214
+ // Aggregate file status (scan + optimize + transcode + urls)
215
+ const { data: status } = await sm.storage.getFileStatus(fileId)
216
+
173
217
  // Split upload (server-side: get URL → client uploads to S3 → complete)
174
218
  const { data: upload } = await sm.storage.getUploadUrl('photo.jpg', 'image/jpeg')
175
219
  // ... client uploads to upload.upload_url ...
@@ -211,9 +255,11 @@ const { data } = await sm.data.aggregate('orders', {
211
255
  ## Video
212
256
 
213
257
  ```ts
214
- const { data } = await sm.video.upload(videoFile, {
215
- onProgress: (pct) => console.log(`${pct}%`),
216
- })
258
+ // Recommended: upload via storage and register for transcoding
259
+ const { data: video } = await sm.video.uploadViaStorage(videoFile)
260
+ // video: { file_id, original_view_url, hls_url_promise }
261
+
262
+ // Lookup an existing video
217
263
  const { data } = await sm.video.get(videoId)
218
264
  const { data } = await sm.video.getStreamUrl(videoId)
219
265
  await sm.video.trackPlayback(videoId, { event: 'play', position: 0 })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.43",
3
+ "version": "0.0.44",
4
4
  "description": "Official TypeScript/JavaScript SDK for ScaleMule Backend-as-a-Service",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",