@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 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/dist/index.d.mts CHANGED
@@ -1170,11 +1170,18 @@ interface FileStatus {
1170
1170
  manifest_url?: string;
1171
1171
  } | null;
1172
1172
  urls: {
1173
- /** Gateway path for the original bytes — `/v1/storage/files/{id}` */
1174
- original: string;
1175
- /** Gateway path for the photo transform — image MIME types only */
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 — video MIME types only */
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
- /** Gateway path for the original bytes — `/v1/storage/files/{id}` */
1174
- original: string;
1175
- /** Gateway path for the photo transform — image MIME types only */
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 — video MIME types only */
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.43",
3
+ "version": "0.0.45",
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",