@scalemule/sdk 0.0.43 → 0.0.45
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/dist/index.d.mts +25 -4
- package/dist/index.d.ts +25 -4
- package/dist/index.js +14 -0
- package/dist/index.mjs +14 -0
- 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 })
|
package/dist/index.d.mts
CHANGED
|
@@ -1170,11 +1170,18 @@ interface FileStatus {
|
|
|
1170
1170
|
manifest_url?: string;
|
|
1171
1171
|
} | null;
|
|
1172
1172
|
urls: {
|
|
1173
|
-
/**
|
|
1174
|
-
|
|
1175
|
-
|
|
1173
|
+
/**
|
|
1174
|
+
* Direct-to-CDN view URL (CloudFront-signed where configured,
|
|
1175
|
+
* S3-presigned otherwise). Absent when scan is `threat` /
|
|
1176
|
+
* `quarantined` / `error` — consumers render a blocked
|
|
1177
|
+
* placeholder when this is null + scan is non-clean.
|
|
1178
|
+
*/
|
|
1179
|
+
original?: string;
|
|
1180
|
+
/** Gateway path for the photo transform — present only when the
|
|
1181
|
+
* photo pipeline reports `optimize.status === 'done'` (image only). */
|
|
1176
1182
|
optimized?: string;
|
|
1177
|
-
/** Gateway path for the HLS master playlist —
|
|
1183
|
+
/** Gateway path for the HLS master playlist — present only when the
|
|
1184
|
+
* transcode worker reports `transcode.status === 'done'` (video only). */
|
|
1178
1185
|
hls?: string;
|
|
1179
1186
|
};
|
|
1180
1187
|
}
|
|
@@ -1301,6 +1308,20 @@ declare class StorageService extends ServiceModule {
|
|
|
1301
1308
|
* ```
|
|
1302
1309
|
*/
|
|
1303
1310
|
getFileStatus(fileId: string, options?: RequestOptions): Promise<ApiResponse<FileStatus>>;
|
|
1311
|
+
/**
|
|
1312
|
+
* Read the application's active media policy. Lightweight endpoint
|
|
1313
|
+
* (`GET /v1/storage/policy`) used by the SDK on boot to pick up the
|
|
1314
|
+
* platform-default `media_policy` without requiring app-admin auth.
|
|
1315
|
+
*
|
|
1316
|
+
* @example
|
|
1317
|
+
* ```ts
|
|
1318
|
+
* const { data } = await client.storage.getPolicy();
|
|
1319
|
+
* console.log(data?.media_policy); // 'safe_visible'
|
|
1320
|
+
* ```
|
|
1321
|
+
*/
|
|
1322
|
+
getPolicy(options?: RequestOptions): Promise<ApiResponse<{
|
|
1323
|
+
media_policy: MediaPolicy;
|
|
1324
|
+
}>>;
|
|
1304
1325
|
/**
|
|
1305
1326
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
1306
1327
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
package/dist/index.d.ts
CHANGED
|
@@ -1170,11 +1170,18 @@ interface FileStatus {
|
|
|
1170
1170
|
manifest_url?: string;
|
|
1171
1171
|
} | null;
|
|
1172
1172
|
urls: {
|
|
1173
|
-
/**
|
|
1174
|
-
|
|
1175
|
-
|
|
1173
|
+
/**
|
|
1174
|
+
* Direct-to-CDN view URL (CloudFront-signed where configured,
|
|
1175
|
+
* S3-presigned otherwise). Absent when scan is `threat` /
|
|
1176
|
+
* `quarantined` / `error` — consumers render a blocked
|
|
1177
|
+
* placeholder when this is null + scan is non-clean.
|
|
1178
|
+
*/
|
|
1179
|
+
original?: string;
|
|
1180
|
+
/** Gateway path for the photo transform — present only when the
|
|
1181
|
+
* photo pipeline reports `optimize.status === 'done'` (image only). */
|
|
1176
1182
|
optimized?: string;
|
|
1177
|
-
/** Gateway path for the HLS master playlist —
|
|
1183
|
+
/** Gateway path for the HLS master playlist — present only when the
|
|
1184
|
+
* transcode worker reports `transcode.status === 'done'` (video only). */
|
|
1178
1185
|
hls?: string;
|
|
1179
1186
|
};
|
|
1180
1187
|
}
|
|
@@ -1301,6 +1308,20 @@ declare class StorageService extends ServiceModule {
|
|
|
1301
1308
|
* ```
|
|
1302
1309
|
*/
|
|
1303
1310
|
getFileStatus(fileId: string, options?: RequestOptions): Promise<ApiResponse<FileStatus>>;
|
|
1311
|
+
/**
|
|
1312
|
+
* Read the application's active media policy. Lightweight endpoint
|
|
1313
|
+
* (`GET /v1/storage/policy`) used by the SDK on boot to pick up the
|
|
1314
|
+
* platform-default `media_policy` without requiring app-admin auth.
|
|
1315
|
+
*
|
|
1316
|
+
* @example
|
|
1317
|
+
* ```ts
|
|
1318
|
+
* const { data } = await client.storage.getPolicy();
|
|
1319
|
+
* console.log(data?.media_policy); // 'safe_visible'
|
|
1320
|
+
* ```
|
|
1321
|
+
*/
|
|
1322
|
+
getPolicy(options?: RequestOptions): Promise<ApiResponse<{
|
|
1323
|
+
media_policy: MediaPolicy;
|
|
1324
|
+
}>>;
|
|
1304
1325
|
/**
|
|
1305
1326
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
1306
1327
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
package/dist/index.js
CHANGED
|
@@ -2988,6 +2988,20 @@ var StorageService = class extends ServiceModule {
|
|
|
2988
2988
|
async getFileStatus(fileId, options) {
|
|
2989
2989
|
return this._get(`/files/${fileId}/status`, options);
|
|
2990
2990
|
}
|
|
2991
|
+
/**
|
|
2992
|
+
* Read the application's active media policy. Lightweight endpoint
|
|
2993
|
+
* (`GET /v1/storage/policy`) used by the SDK on boot to pick up the
|
|
2994
|
+
* platform-default `media_policy` without requiring app-admin auth.
|
|
2995
|
+
*
|
|
2996
|
+
* @example
|
|
2997
|
+
* ```ts
|
|
2998
|
+
* const { data } = await client.storage.getPolicy();
|
|
2999
|
+
* console.log(data?.media_policy); // 'safe_visible'
|
|
3000
|
+
* ```
|
|
3001
|
+
*/
|
|
3002
|
+
async getPolicy(options) {
|
|
3003
|
+
return this._get(`/policy`, options);
|
|
3004
|
+
}
|
|
2991
3005
|
/**
|
|
2992
3006
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
2993
3007
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
package/dist/index.mjs
CHANGED
|
@@ -2618,6 +2618,20 @@ var StorageService = class extends ServiceModule {
|
|
|
2618
2618
|
async getFileStatus(fileId, options) {
|
|
2619
2619
|
return this._get(`/files/${fileId}/status`, options);
|
|
2620
2620
|
}
|
|
2621
|
+
/**
|
|
2622
|
+
* Read the application's active media policy. Lightweight endpoint
|
|
2623
|
+
* (`GET /v1/storage/policy`) used by the SDK on boot to pick up the
|
|
2624
|
+
* platform-default `media_policy` without requiring app-admin auth.
|
|
2625
|
+
*
|
|
2626
|
+
* @example
|
|
2627
|
+
* ```ts
|
|
2628
|
+
* const { data } = await client.storage.getPolicy();
|
|
2629
|
+
* console.log(data?.media_policy); // 'safe_visible'
|
|
2630
|
+
* ```
|
|
2631
|
+
*/
|
|
2632
|
+
async getPolicy(options) {
|
|
2633
|
+
return this._get(`/policy`, options);
|
|
2634
|
+
}
|
|
2621
2635
|
/**
|
|
2622
2636
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
2623
2637
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|