@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.
- package/README.md +49 -3
- 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
|
-
|
|
215
|
-
|
|
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 })
|