@scalemule/sdk 0.0.37 → 0.0.39
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/dist/index.d.mts +177 -0
- package/dist/index.d.ts +177 -0
- package/dist/index.js +241 -6
- package/dist/index.mjs +241 -6
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -1134,6 +1134,23 @@ declare class StorageService extends ServiceModule {
|
|
|
1134
1134
|
* @returns The completed file record with id, url, etc.
|
|
1135
1135
|
*/
|
|
1136
1136
|
upload(file: File | Blob, options?: UploadOptions): Promise<ApiResponse<FileInfo>>;
|
|
1137
|
+
/**
|
|
1138
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
1139
|
+
*
|
|
1140
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
1141
|
+
* - `is_public: false` — caller cannot opt out
|
|
1142
|
+
* - no client-side compression — preserve the original bytes
|
|
1143
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
1144
|
+
*
|
|
1145
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
1146
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
1147
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
1148
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
1149
|
+
*
|
|
1150
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
1151
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
1152
|
+
*/
|
|
1153
|
+
uploadPrivate(file: File | Blob, options?: Omit<UploadOptions, 'isPublic' | 'skipCompression'>): Promise<ApiResponse<FileInfo>>;
|
|
1137
1154
|
private uploadDirect;
|
|
1138
1155
|
private uploadMultipart;
|
|
1139
1156
|
private abortMultipart;
|
|
@@ -1674,8 +1691,47 @@ interface VideoInfo {
|
|
|
1674
1691
|
created_at: string;
|
|
1675
1692
|
updated_at: string;
|
|
1676
1693
|
}
|
|
1694
|
+
/** Request body for {@link VideoService.register}. */
|
|
1695
|
+
interface RegisterVideoRequest {
|
|
1696
|
+
/** Storage file_id of the previously-uploaded video. */
|
|
1697
|
+
fileId: string;
|
|
1698
|
+
/** Optional override; defaults to the gateway-injected x-user-id. */
|
|
1699
|
+
userId?: string;
|
|
1700
|
+
}
|
|
1701
|
+
/** Response shape from POST /v1/videos/register. */
|
|
1702
|
+
interface RegisterVideoResponse {
|
|
1703
|
+
video_id: string;
|
|
1704
|
+
file_id: string;
|
|
1705
|
+
/** `registering` (scan was clean) | `pending_scan` (scan in progress) */
|
|
1706
|
+
status: 'registering' | 'pending_scan';
|
|
1707
|
+
original_view_url: string;
|
|
1708
|
+
}
|
|
1709
|
+
/** Result of {@link VideoService.uploadViaStorage}. */
|
|
1710
|
+
interface VideoUploadViaStorageResult {
|
|
1711
|
+
/** Storage file_id — store this in chat-attachment metadata. */
|
|
1712
|
+
file_id: string;
|
|
1713
|
+
/** Video service id. Equals `file_id` for storage-backed videos. */
|
|
1714
|
+
video_id: string;
|
|
1715
|
+
/**
|
|
1716
|
+
* Short-lived signed URL to the original bytes. Usable immediately on the
|
|
1717
|
+
* recipient side, before HLS transcoding completes.
|
|
1718
|
+
*/
|
|
1719
|
+
original_view_url: string | null;
|
|
1720
|
+
/**
|
|
1721
|
+
* Resolves once the transcode worker finishes (or times out at 30s).
|
|
1722
|
+
* On resolution: an HLS master playlist URL. On timeout: `null` — caller
|
|
1723
|
+
* should fall back to `original_view_url` and try the playlist later.
|
|
1724
|
+
*/
|
|
1725
|
+
hls_url_promise: Promise<string | null>;
|
|
1726
|
+
}
|
|
1677
1727
|
declare class VideoService extends ServiceModule {
|
|
1728
|
+
private readonly storage;
|
|
1678
1729
|
protected basePath: string;
|
|
1730
|
+
/**
|
|
1731
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
1732
|
+
* top-level {@link ScaleMule} constructor.
|
|
1733
|
+
*/
|
|
1734
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
1679
1735
|
/**
|
|
1680
1736
|
* Upload a video file using chunked multipart upload.
|
|
1681
1737
|
*
|
|
@@ -1689,6 +1745,61 @@ declare class VideoService extends ServiceModule {
|
|
|
1689
1745
|
upload(file: File | Blob, options?: VideoUploadOptions, requestOptions?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1690
1746
|
/** Get video metadata and status. */
|
|
1691
1747
|
get(videoId: string, options?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1748
|
+
/**
|
|
1749
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
1750
|
+
*
|
|
1751
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
1752
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
1753
|
+
* - clean → 201, video record created with status='uploading',
|
|
1754
|
+
* transcode worker advances on `scan.file.completed`
|
|
1755
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
1756
|
+
* worker advances when scan completes
|
|
1757
|
+
* - threat → 409 (rejected; row not created)
|
|
1758
|
+
*
|
|
1759
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
1760
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
1761
|
+
*
|
|
1762
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
1763
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
1764
|
+
* `getStreamUrl()` / `get()`.
|
|
1765
|
+
*
|
|
1766
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
1767
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
1768
|
+
*/
|
|
1769
|
+
register(request: RegisterVideoRequest, options?: RequestOptions): Promise<ApiResponse<RegisterVideoResponse>>;
|
|
1770
|
+
/**
|
|
1771
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
1772
|
+
* compression) and register it with the video service so transcoding
|
|
1773
|
+
* + HLS streaming work.
|
|
1774
|
+
*
|
|
1775
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
1776
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
1777
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
1778
|
+
* once the transcoder finishes.
|
|
1779
|
+
*
|
|
1780
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
1781
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
1782
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
1783
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
1784
|
+
*
|
|
1785
|
+
* If `register()` fails after a successful storage upload, the file
|
|
1786
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
1787
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
1788
|
+
* to `null`.
|
|
1789
|
+
*/
|
|
1790
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
1791
|
+
userId?: string;
|
|
1792
|
+
filename?: string;
|
|
1793
|
+
metadata?: Record<string, unknown>;
|
|
1794
|
+
onProgress?: (progress: number) => void;
|
|
1795
|
+
signal?: AbortSignal;
|
|
1796
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<VideoUploadViaStorageResult>>;
|
|
1797
|
+
/**
|
|
1798
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
1799
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
1800
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
1801
|
+
*/
|
|
1802
|
+
private pollTranscodeComplete;
|
|
1692
1803
|
/**
|
|
1693
1804
|
* Get the HLS master playlist URL for streaming.
|
|
1694
1805
|
* Returns the playlist URL that can be passed to a video player.
|
|
@@ -4222,8 +4333,39 @@ interface TransformOptions {
|
|
|
4222
4333
|
* URLs built with these sizes + fit=cover get instant cache hits (no server-side transform).
|
|
4223
4334
|
*/
|
|
4224
4335
|
declare const PHOTO_BREAKPOINTS: readonly [36, 150, 320, 640, 1080];
|
|
4336
|
+
/** Result of {@link PhotoService.uploadViaStorage}. */
|
|
4337
|
+
interface UploadViaStorageResult {
|
|
4338
|
+
/** Storage file_id — pass this to chat-message attachment metadata. */
|
|
4339
|
+
file_id: string;
|
|
4340
|
+
/**
|
|
4341
|
+
* Photo service's photo_id. Use with `getTransformUrl()` /
|
|
4342
|
+
* `getOptimalUrl()` to fetch responsive variants. `null` when register
|
|
4343
|
+
* failed after a successful storage upload (the file_id is still usable
|
|
4344
|
+
* as a generic storage file).
|
|
4345
|
+
*/
|
|
4346
|
+
photo_id: string | null;
|
|
4347
|
+
/**
|
|
4348
|
+
* Short-lived signed URL to the original bytes — usable immediately on the
|
|
4349
|
+
* recipient side, before optimization completes.
|
|
4350
|
+
*/
|
|
4351
|
+
original_view_url: string | null;
|
|
4352
|
+
/**
|
|
4353
|
+
* Resolves once the optimization worker finishes (or times out at 10s).
|
|
4354
|
+
* On resolution: a transform URL pointing at the largest pre-cached
|
|
4355
|
+
* breakpoint. On timeout: `null` — caller should fall back to
|
|
4356
|
+
* `getTransformUrl()` which uses the on-demand transform path.
|
|
4357
|
+
*/
|
|
4358
|
+
optimized_url_promise: Promise<string | null>;
|
|
4359
|
+
}
|
|
4225
4360
|
declare class PhotoService extends ServiceModule {
|
|
4361
|
+
private readonly storage;
|
|
4226
4362
|
protected basePath: string;
|
|
4363
|
+
/**
|
|
4364
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
4365
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
4366
|
+
* instantiate `PhotoService` directly.
|
|
4367
|
+
*/
|
|
4368
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
4227
4369
|
upload(file: File | Blob, uploadOptions?: {
|
|
4228
4370
|
metadata?: Record<string, unknown>;
|
|
4229
4371
|
onProgress?: (progress: number) => void;
|
|
@@ -4311,6 +4453,41 @@ declare class PhotoService extends ServiceModule {
|
|
|
4311
4453
|
fileId: string;
|
|
4312
4454
|
userId?: string;
|
|
4313
4455
|
}, requestOptions?: RequestOptions): Promise<ApiResponse<PhotoInfo>>;
|
|
4456
|
+
/**
|
|
4457
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
4458
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
4459
|
+
*
|
|
4460
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
4461
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
4462
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
4463
|
+
* usable URLs.
|
|
4464
|
+
*
|
|
4465
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
4466
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
4467
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
4468
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
4469
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
4470
|
+
* subscription.
|
|
4471
|
+
*
|
|
4472
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
4473
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
4474
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
4475
|
+
* `optimized_url_promise` to `null`.
|
|
4476
|
+
*/
|
|
4477
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
4478
|
+
userId?: string;
|
|
4479
|
+
filename?: string;
|
|
4480
|
+
metadata?: Record<string, unknown>;
|
|
4481
|
+
onProgress?: (progress: number) => void;
|
|
4482
|
+
signal?: AbortSignal;
|
|
4483
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<UploadViaStorageResult>>;
|
|
4484
|
+
/**
|
|
4485
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
4486
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
4487
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
4488
|
+
* which uses the on-demand transform path).
|
|
4489
|
+
*/
|
|
4490
|
+
private pollOptimizationComplete;
|
|
4314
4491
|
/** @deprecated Use upload() instead */
|
|
4315
4492
|
uploadPhoto(file: File | Blob, options?: {
|
|
4316
4493
|
metadata?: Record<string, unknown>;
|
package/dist/index.d.ts
CHANGED
|
@@ -1134,6 +1134,23 @@ declare class StorageService extends ServiceModule {
|
|
|
1134
1134
|
* @returns The completed file record with id, url, etc.
|
|
1135
1135
|
*/
|
|
1136
1136
|
upload(file: File | Blob, options?: UploadOptions): Promise<ApiResponse<FileInfo>>;
|
|
1137
|
+
/**
|
|
1138
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
1139
|
+
*
|
|
1140
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
1141
|
+
* - `is_public: false` — caller cannot opt out
|
|
1142
|
+
* - no client-side compression — preserve the original bytes
|
|
1143
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
1144
|
+
*
|
|
1145
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
1146
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
1147
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
1148
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
1149
|
+
*
|
|
1150
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
1151
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
1152
|
+
*/
|
|
1153
|
+
uploadPrivate(file: File | Blob, options?: Omit<UploadOptions, 'isPublic' | 'skipCompression'>): Promise<ApiResponse<FileInfo>>;
|
|
1137
1154
|
private uploadDirect;
|
|
1138
1155
|
private uploadMultipart;
|
|
1139
1156
|
private abortMultipart;
|
|
@@ -1674,8 +1691,47 @@ interface VideoInfo {
|
|
|
1674
1691
|
created_at: string;
|
|
1675
1692
|
updated_at: string;
|
|
1676
1693
|
}
|
|
1694
|
+
/** Request body for {@link VideoService.register}. */
|
|
1695
|
+
interface RegisterVideoRequest {
|
|
1696
|
+
/** Storage file_id of the previously-uploaded video. */
|
|
1697
|
+
fileId: string;
|
|
1698
|
+
/** Optional override; defaults to the gateway-injected x-user-id. */
|
|
1699
|
+
userId?: string;
|
|
1700
|
+
}
|
|
1701
|
+
/** Response shape from POST /v1/videos/register. */
|
|
1702
|
+
interface RegisterVideoResponse {
|
|
1703
|
+
video_id: string;
|
|
1704
|
+
file_id: string;
|
|
1705
|
+
/** `registering` (scan was clean) | `pending_scan` (scan in progress) */
|
|
1706
|
+
status: 'registering' | 'pending_scan';
|
|
1707
|
+
original_view_url: string;
|
|
1708
|
+
}
|
|
1709
|
+
/** Result of {@link VideoService.uploadViaStorage}. */
|
|
1710
|
+
interface VideoUploadViaStorageResult {
|
|
1711
|
+
/** Storage file_id — store this in chat-attachment metadata. */
|
|
1712
|
+
file_id: string;
|
|
1713
|
+
/** Video service id. Equals `file_id` for storage-backed videos. */
|
|
1714
|
+
video_id: string;
|
|
1715
|
+
/**
|
|
1716
|
+
* Short-lived signed URL to the original bytes. Usable immediately on the
|
|
1717
|
+
* recipient side, before HLS transcoding completes.
|
|
1718
|
+
*/
|
|
1719
|
+
original_view_url: string | null;
|
|
1720
|
+
/**
|
|
1721
|
+
* Resolves once the transcode worker finishes (or times out at 30s).
|
|
1722
|
+
* On resolution: an HLS master playlist URL. On timeout: `null` — caller
|
|
1723
|
+
* should fall back to `original_view_url` and try the playlist later.
|
|
1724
|
+
*/
|
|
1725
|
+
hls_url_promise: Promise<string | null>;
|
|
1726
|
+
}
|
|
1677
1727
|
declare class VideoService extends ServiceModule {
|
|
1728
|
+
private readonly storage;
|
|
1678
1729
|
protected basePath: string;
|
|
1730
|
+
/**
|
|
1731
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
1732
|
+
* top-level {@link ScaleMule} constructor.
|
|
1733
|
+
*/
|
|
1734
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
1679
1735
|
/**
|
|
1680
1736
|
* Upload a video file using chunked multipart upload.
|
|
1681
1737
|
*
|
|
@@ -1689,6 +1745,61 @@ declare class VideoService extends ServiceModule {
|
|
|
1689
1745
|
upload(file: File | Blob, options?: VideoUploadOptions, requestOptions?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1690
1746
|
/** Get video metadata and status. */
|
|
1691
1747
|
get(videoId: string, options?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1748
|
+
/**
|
|
1749
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
1750
|
+
*
|
|
1751
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
1752
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
1753
|
+
* - clean → 201, video record created with status='uploading',
|
|
1754
|
+
* transcode worker advances on `scan.file.completed`
|
|
1755
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
1756
|
+
* worker advances when scan completes
|
|
1757
|
+
* - threat → 409 (rejected; row not created)
|
|
1758
|
+
*
|
|
1759
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
1760
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
1761
|
+
*
|
|
1762
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
1763
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
1764
|
+
* `getStreamUrl()` / `get()`.
|
|
1765
|
+
*
|
|
1766
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
1767
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
1768
|
+
*/
|
|
1769
|
+
register(request: RegisterVideoRequest, options?: RequestOptions): Promise<ApiResponse<RegisterVideoResponse>>;
|
|
1770
|
+
/**
|
|
1771
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
1772
|
+
* compression) and register it with the video service so transcoding
|
|
1773
|
+
* + HLS streaming work.
|
|
1774
|
+
*
|
|
1775
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
1776
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
1777
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
1778
|
+
* once the transcoder finishes.
|
|
1779
|
+
*
|
|
1780
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
1781
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
1782
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
1783
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
1784
|
+
*
|
|
1785
|
+
* If `register()` fails after a successful storage upload, the file
|
|
1786
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
1787
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
1788
|
+
* to `null`.
|
|
1789
|
+
*/
|
|
1790
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
1791
|
+
userId?: string;
|
|
1792
|
+
filename?: string;
|
|
1793
|
+
metadata?: Record<string, unknown>;
|
|
1794
|
+
onProgress?: (progress: number) => void;
|
|
1795
|
+
signal?: AbortSignal;
|
|
1796
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<VideoUploadViaStorageResult>>;
|
|
1797
|
+
/**
|
|
1798
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
1799
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
1800
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
1801
|
+
*/
|
|
1802
|
+
private pollTranscodeComplete;
|
|
1692
1803
|
/**
|
|
1693
1804
|
* Get the HLS master playlist URL for streaming.
|
|
1694
1805
|
* Returns the playlist URL that can be passed to a video player.
|
|
@@ -4222,8 +4333,39 @@ interface TransformOptions {
|
|
|
4222
4333
|
* URLs built with these sizes + fit=cover get instant cache hits (no server-side transform).
|
|
4223
4334
|
*/
|
|
4224
4335
|
declare const PHOTO_BREAKPOINTS: readonly [36, 150, 320, 640, 1080];
|
|
4336
|
+
/** Result of {@link PhotoService.uploadViaStorage}. */
|
|
4337
|
+
interface UploadViaStorageResult {
|
|
4338
|
+
/** Storage file_id — pass this to chat-message attachment metadata. */
|
|
4339
|
+
file_id: string;
|
|
4340
|
+
/**
|
|
4341
|
+
* Photo service's photo_id. Use with `getTransformUrl()` /
|
|
4342
|
+
* `getOptimalUrl()` to fetch responsive variants. `null` when register
|
|
4343
|
+
* failed after a successful storage upload (the file_id is still usable
|
|
4344
|
+
* as a generic storage file).
|
|
4345
|
+
*/
|
|
4346
|
+
photo_id: string | null;
|
|
4347
|
+
/**
|
|
4348
|
+
* Short-lived signed URL to the original bytes — usable immediately on the
|
|
4349
|
+
* recipient side, before optimization completes.
|
|
4350
|
+
*/
|
|
4351
|
+
original_view_url: string | null;
|
|
4352
|
+
/**
|
|
4353
|
+
* Resolves once the optimization worker finishes (or times out at 10s).
|
|
4354
|
+
* On resolution: a transform URL pointing at the largest pre-cached
|
|
4355
|
+
* breakpoint. On timeout: `null` — caller should fall back to
|
|
4356
|
+
* `getTransformUrl()` which uses the on-demand transform path.
|
|
4357
|
+
*/
|
|
4358
|
+
optimized_url_promise: Promise<string | null>;
|
|
4359
|
+
}
|
|
4225
4360
|
declare class PhotoService extends ServiceModule {
|
|
4361
|
+
private readonly storage;
|
|
4226
4362
|
protected basePath: string;
|
|
4363
|
+
/**
|
|
4364
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
4365
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
4366
|
+
* instantiate `PhotoService` directly.
|
|
4367
|
+
*/
|
|
4368
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
4227
4369
|
upload(file: File | Blob, uploadOptions?: {
|
|
4228
4370
|
metadata?: Record<string, unknown>;
|
|
4229
4371
|
onProgress?: (progress: number) => void;
|
|
@@ -4311,6 +4453,41 @@ declare class PhotoService extends ServiceModule {
|
|
|
4311
4453
|
fileId: string;
|
|
4312
4454
|
userId?: string;
|
|
4313
4455
|
}, requestOptions?: RequestOptions): Promise<ApiResponse<PhotoInfo>>;
|
|
4456
|
+
/**
|
|
4457
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
4458
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
4459
|
+
*
|
|
4460
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
4461
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
4462
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
4463
|
+
* usable URLs.
|
|
4464
|
+
*
|
|
4465
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
4466
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
4467
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
4468
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
4469
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
4470
|
+
* subscription.
|
|
4471
|
+
*
|
|
4472
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
4473
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
4474
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
4475
|
+
* `optimized_url_promise` to `null`.
|
|
4476
|
+
*/
|
|
4477
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
4478
|
+
userId?: string;
|
|
4479
|
+
filename?: string;
|
|
4480
|
+
metadata?: Record<string, unknown>;
|
|
4481
|
+
onProgress?: (progress: number) => void;
|
|
4482
|
+
signal?: AbortSignal;
|
|
4483
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<UploadViaStorageResult>>;
|
|
4484
|
+
/**
|
|
4485
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
4486
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
4487
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
4488
|
+
* which uses the on-demand transform path).
|
|
4489
|
+
*/
|
|
4490
|
+
private pollOptimizationComplete;
|
|
4314
4491
|
/** @deprecated Use upload() instead */
|
|
4315
4492
|
uploadPhoto(file: File | Blob, options?: {
|
|
4316
4493
|
metadata?: Record<string, unknown>;
|
package/dist/index.js
CHANGED
|
@@ -2335,6 +2335,40 @@ var StorageService = class extends ServiceModule {
|
|
|
2335
2335
|
return { data: null, error: { code: "upload_error", message, status: 0 } };
|
|
2336
2336
|
}
|
|
2337
2337
|
}
|
|
2338
|
+
/**
|
|
2339
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
2340
|
+
*
|
|
2341
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
2342
|
+
* - `is_public: false` — caller cannot opt out
|
|
2343
|
+
* - no client-side compression — preserve the original bytes
|
|
2344
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
2345
|
+
*
|
|
2346
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
2347
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
2348
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
2349
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
2350
|
+
*
|
|
2351
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
2352
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
2353
|
+
*/
|
|
2354
|
+
async uploadPrivate(file, options) {
|
|
2355
|
+
const result = await this.upload(file, {
|
|
2356
|
+
...options,
|
|
2357
|
+
isPublic: false,
|
|
2358
|
+
skipCompression: true
|
|
2359
|
+
});
|
|
2360
|
+
if (result.data && result.data.is_public === true) {
|
|
2361
|
+
return {
|
|
2362
|
+
data: null,
|
|
2363
|
+
error: {
|
|
2364
|
+
code: "visibility_violation",
|
|
2365
|
+
message: "Storage returned is_public=true for an uploadPrivate() call. This usually indicates a server-side bug or an admin override; the caller asked for a private upload.",
|
|
2366
|
+
status: 0
|
|
2367
|
+
}
|
|
2368
|
+
};
|
|
2369
|
+
}
|
|
2370
|
+
return result;
|
|
2371
|
+
}
|
|
2338
2372
|
// --------------------------------------------------------------------------
|
|
2339
2373
|
// Direct Upload (3-step with retry + stall)
|
|
2340
2374
|
// --------------------------------------------------------------------------
|
|
@@ -4031,8 +4065,13 @@ var RealtimeService = class extends ServiceModule {
|
|
|
4031
4065
|
var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
4032
4066
|
var MIN_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
4033
4067
|
var VideoService = class extends ServiceModule {
|
|
4034
|
-
|
|
4035
|
-
|
|
4068
|
+
/**
|
|
4069
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
4070
|
+
* top-level {@link ScaleMule} constructor.
|
|
4071
|
+
*/
|
|
4072
|
+
constructor(client, storage) {
|
|
4073
|
+
super(client);
|
|
4074
|
+
this.storage = storage;
|
|
4036
4075
|
this.basePath = "/v1/videos";
|
|
4037
4076
|
}
|
|
4038
4077
|
// --------------------------------------------------------------------------
|
|
@@ -4106,6 +4145,115 @@ var VideoService = class extends ServiceModule {
|
|
|
4106
4145
|
async get(videoId, options) {
|
|
4107
4146
|
return super._get(`/${videoId}`, options);
|
|
4108
4147
|
}
|
|
4148
|
+
/**
|
|
4149
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
4150
|
+
*
|
|
4151
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
4152
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
4153
|
+
* - clean → 201, video record created with status='uploading',
|
|
4154
|
+
* transcode worker advances on `scan.file.completed`
|
|
4155
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
4156
|
+
* worker advances when scan completes
|
|
4157
|
+
* - threat → 409 (rejected; row not created)
|
|
4158
|
+
*
|
|
4159
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
4160
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
4161
|
+
*
|
|
4162
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
4163
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
4164
|
+
* `getStreamUrl()` / `get()`.
|
|
4165
|
+
*
|
|
4166
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
4167
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
4168
|
+
*/
|
|
4169
|
+
async register(request, options) {
|
|
4170
|
+
return this.post(
|
|
4171
|
+
"/register",
|
|
4172
|
+
{
|
|
4173
|
+
file_id: request.fileId,
|
|
4174
|
+
sm_user_id: request.userId
|
|
4175
|
+
},
|
|
4176
|
+
options
|
|
4177
|
+
);
|
|
4178
|
+
}
|
|
4179
|
+
/**
|
|
4180
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
4181
|
+
* compression) and register it with the video service so transcoding
|
|
4182
|
+
* + HLS streaming work.
|
|
4183
|
+
*
|
|
4184
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
4185
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
4186
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
4187
|
+
* once the transcoder finishes.
|
|
4188
|
+
*
|
|
4189
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
4190
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
4191
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
4192
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
4193
|
+
*
|
|
4194
|
+
* If `register()` fails after a successful storage upload, the file
|
|
4195
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
4196
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
4197
|
+
* to `null`.
|
|
4198
|
+
*/
|
|
4199
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
4200
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
4201
|
+
filename: uploadOptions?.filename,
|
|
4202
|
+
metadata: uploadOptions?.metadata,
|
|
4203
|
+
onProgress: uploadOptions?.onProgress,
|
|
4204
|
+
signal: uploadOptions?.signal
|
|
4205
|
+
});
|
|
4206
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
4207
|
+
return { data: null, error: uploadResult.error };
|
|
4208
|
+
}
|
|
4209
|
+
const fileInfo = uploadResult.data;
|
|
4210
|
+
const fileId = fileInfo.id;
|
|
4211
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
4212
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
4213
|
+
if (registerResult.error || !registerResult.data) {
|
|
4214
|
+
console.warn(
|
|
4215
|
+
"[scalemule-sdk] video.register() failed after storage upload; HLS variants unavailable.",
|
|
4216
|
+
registerResult.error
|
|
4217
|
+
);
|
|
4218
|
+
return {
|
|
4219
|
+
data: {
|
|
4220
|
+
file_id: fileId,
|
|
4221
|
+
video_id: fileId,
|
|
4222
|
+
original_view_url: originalViewUrl,
|
|
4223
|
+
hls_url_promise: Promise.resolve(null)
|
|
4224
|
+
},
|
|
4225
|
+
error: null
|
|
4226
|
+
};
|
|
4227
|
+
}
|
|
4228
|
+
const videoId = registerResult.data.video_id;
|
|
4229
|
+
const hlsUrlPromise = this.pollTranscodeComplete(videoId, requestOptions);
|
|
4230
|
+
return {
|
|
4231
|
+
data: {
|
|
4232
|
+
file_id: fileId,
|
|
4233
|
+
video_id: videoId,
|
|
4234
|
+
original_view_url: originalViewUrl,
|
|
4235
|
+
hls_url_promise: hlsUrlPromise
|
|
4236
|
+
},
|
|
4237
|
+
error: null
|
|
4238
|
+
};
|
|
4239
|
+
}
|
|
4240
|
+
/**
|
|
4241
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
4242
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
4243
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
4244
|
+
*/
|
|
4245
|
+
async pollTranscodeComplete(videoId, requestOptions) {
|
|
4246
|
+
const intervalMs = 1e3;
|
|
4247
|
+
const maxAttempts = 30;
|
|
4248
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
4249
|
+
const result = await this.get(videoId, requestOptions);
|
|
4250
|
+
if (result.data?.status === "ready") {
|
|
4251
|
+
return `${this.client.getBaseUrl()}${this.basePath}/${videoId}/playlist.m3u8`;
|
|
4252
|
+
}
|
|
4253
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
4254
|
+
}
|
|
4255
|
+
return null;
|
|
4256
|
+
}
|
|
4109
4257
|
/**
|
|
4110
4258
|
* Get the HLS master playlist URL for streaming.
|
|
4111
4259
|
* Returns the playlist URL that can be passed to a video player.
|
|
@@ -6042,8 +6190,14 @@ var SearchService = class extends ServiceModule {
|
|
|
6042
6190
|
// src/services/photo.ts
|
|
6043
6191
|
var PHOTO_BREAKPOINTS = [36, 150, 320, 640, 1080];
|
|
6044
6192
|
var PhotoService = class extends ServiceModule {
|
|
6045
|
-
|
|
6046
|
-
|
|
6193
|
+
/**
|
|
6194
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
6195
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
6196
|
+
* instantiate `PhotoService` directly.
|
|
6197
|
+
*/
|
|
6198
|
+
constructor(client, storage) {
|
|
6199
|
+
super(client);
|
|
6200
|
+
this.storage = storage;
|
|
6047
6201
|
this.basePath = "/v1/photos";
|
|
6048
6202
|
}
|
|
6049
6203
|
async upload(file, uploadOptions, requestOptions) {
|
|
@@ -6183,6 +6337,87 @@ var PhotoService = class extends ServiceModule {
|
|
|
6183
6337
|
}
|
|
6184
6338
|
};
|
|
6185
6339
|
}
|
|
6340
|
+
/**
|
|
6341
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
6342
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
6343
|
+
*
|
|
6344
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
6345
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
6346
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
6347
|
+
* usable URLs.
|
|
6348
|
+
*
|
|
6349
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
6350
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
6351
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
6352
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
6353
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
6354
|
+
* subscription.
|
|
6355
|
+
*
|
|
6356
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
6357
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
6358
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
6359
|
+
* `optimized_url_promise` to `null`.
|
|
6360
|
+
*/
|
|
6361
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
6362
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
6363
|
+
filename: uploadOptions?.filename,
|
|
6364
|
+
metadata: uploadOptions?.metadata,
|
|
6365
|
+
onProgress: uploadOptions?.onProgress,
|
|
6366
|
+
signal: uploadOptions?.signal
|
|
6367
|
+
});
|
|
6368
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
6369
|
+
return { data: null, error: uploadResult.error };
|
|
6370
|
+
}
|
|
6371
|
+
const fileInfo = uploadResult.data;
|
|
6372
|
+
const fileId = fileInfo.id;
|
|
6373
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
6374
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
6375
|
+
if (registerResult.error || !registerResult.data) {
|
|
6376
|
+
console.warn(
|
|
6377
|
+
"[scalemule-sdk] photo.register() failed after storage upload; optimized variants unavailable.",
|
|
6378
|
+
registerResult.error
|
|
6379
|
+
);
|
|
6380
|
+
return {
|
|
6381
|
+
data: {
|
|
6382
|
+
file_id: fileId,
|
|
6383
|
+
photo_id: null,
|
|
6384
|
+
original_view_url: originalViewUrl,
|
|
6385
|
+
optimized_url_promise: Promise.resolve(null)
|
|
6386
|
+
},
|
|
6387
|
+
error: null
|
|
6388
|
+
};
|
|
6389
|
+
}
|
|
6390
|
+
const photoId = registerResult.data.id;
|
|
6391
|
+
const optimizedUrlPromise = this.pollOptimizationComplete(photoId, requestOptions);
|
|
6392
|
+
return {
|
|
6393
|
+
data: {
|
|
6394
|
+
file_id: fileId,
|
|
6395
|
+
photo_id: photoId,
|
|
6396
|
+
original_view_url: originalViewUrl,
|
|
6397
|
+
optimized_url_promise: optimizedUrlPromise
|
|
6398
|
+
},
|
|
6399
|
+
error: null
|
|
6400
|
+
};
|
|
6401
|
+
}
|
|
6402
|
+
/**
|
|
6403
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
6404
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
6405
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
6406
|
+
* which uses the on-demand transform path).
|
|
6407
|
+
*/
|
|
6408
|
+
async pollOptimizationComplete(photoId, requestOptions) {
|
|
6409
|
+
const intervalMs = 250;
|
|
6410
|
+
const maxAttempts = 40;
|
|
6411
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
6412
|
+
const result = await this.get(photoId, requestOptions);
|
|
6413
|
+
const status = result.data?.optimization_status;
|
|
6414
|
+
if (status === "completed") {
|
|
6415
|
+
return this.getOptimalUrl(photoId, 1080);
|
|
6416
|
+
}
|
|
6417
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
6418
|
+
}
|
|
6419
|
+
return null;
|
|
6420
|
+
}
|
|
6186
6421
|
/** @deprecated Use upload() instead */
|
|
6187
6422
|
async uploadPhoto(file, options) {
|
|
6188
6423
|
return this.upload(file, options);
|
|
@@ -7019,7 +7254,7 @@ var ScaleMule = class {
|
|
|
7019
7254
|
this.auth = new AuthService(this._client);
|
|
7020
7255
|
this.storage = new StorageService(this._client);
|
|
7021
7256
|
this.realtime = new RealtimeService(this._client);
|
|
7022
|
-
this.video = new VideoService(this._client);
|
|
7257
|
+
this.video = new VideoService(this._client, this.storage);
|
|
7023
7258
|
this.data = new DataService(this._client);
|
|
7024
7259
|
this.chat = new ChatService(this._client);
|
|
7025
7260
|
this.conference = new ConferenceService(this._client);
|
|
@@ -7046,7 +7281,7 @@ var ScaleMule = class {
|
|
|
7046
7281
|
this.events = new EventsService(this._client);
|
|
7047
7282
|
this.graph = new GraphService(this._client);
|
|
7048
7283
|
this.functions = new FunctionsService(this._client);
|
|
7049
|
-
this.photo = new PhotoService(this._client);
|
|
7284
|
+
this.photo = new PhotoService(this._client, this.storage);
|
|
7050
7285
|
this.flagContent = new FlagContentService(this._client);
|
|
7051
7286
|
this.creatorMaker = new CreatorMakerService(this._client);
|
|
7052
7287
|
this.compliance = new ComplianceService(this._client);
|
package/dist/index.mjs
CHANGED
|
@@ -1966,6 +1966,40 @@ var StorageService = class extends ServiceModule {
|
|
|
1966
1966
|
return { data: null, error: { code: "upload_error", message, status: 0 } };
|
|
1967
1967
|
}
|
|
1968
1968
|
}
|
|
1969
|
+
/**
|
|
1970
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
1971
|
+
*
|
|
1972
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
1973
|
+
* - `is_public: false` — caller cannot opt out
|
|
1974
|
+
* - no client-side compression — preserve the original bytes
|
|
1975
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
1976
|
+
*
|
|
1977
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
1978
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
1979
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
1980
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
1981
|
+
*
|
|
1982
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
1983
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
1984
|
+
*/
|
|
1985
|
+
async uploadPrivate(file, options) {
|
|
1986
|
+
const result = await this.upload(file, {
|
|
1987
|
+
...options,
|
|
1988
|
+
isPublic: false,
|
|
1989
|
+
skipCompression: true
|
|
1990
|
+
});
|
|
1991
|
+
if (result.data && result.data.is_public === true) {
|
|
1992
|
+
return {
|
|
1993
|
+
data: null,
|
|
1994
|
+
error: {
|
|
1995
|
+
code: "visibility_violation",
|
|
1996
|
+
message: "Storage returned is_public=true for an uploadPrivate() call. This usually indicates a server-side bug or an admin override; the caller asked for a private upload.",
|
|
1997
|
+
status: 0
|
|
1998
|
+
}
|
|
1999
|
+
};
|
|
2000
|
+
}
|
|
2001
|
+
return result;
|
|
2002
|
+
}
|
|
1969
2003
|
// --------------------------------------------------------------------------
|
|
1970
2004
|
// Direct Upload (3-step with retry + stall)
|
|
1971
2005
|
// --------------------------------------------------------------------------
|
|
@@ -3659,8 +3693,13 @@ var RealtimeService = class extends ServiceModule {
|
|
|
3659
3693
|
var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
3660
3694
|
var MIN_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
3661
3695
|
var VideoService = class extends ServiceModule {
|
|
3662
|
-
|
|
3663
|
-
|
|
3696
|
+
/**
|
|
3697
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
3698
|
+
* top-level {@link ScaleMule} constructor.
|
|
3699
|
+
*/
|
|
3700
|
+
constructor(client, storage) {
|
|
3701
|
+
super(client);
|
|
3702
|
+
this.storage = storage;
|
|
3664
3703
|
this.basePath = "/v1/videos";
|
|
3665
3704
|
}
|
|
3666
3705
|
// --------------------------------------------------------------------------
|
|
@@ -3734,6 +3773,115 @@ var VideoService = class extends ServiceModule {
|
|
|
3734
3773
|
async get(videoId, options) {
|
|
3735
3774
|
return super._get(`/${videoId}`, options);
|
|
3736
3775
|
}
|
|
3776
|
+
/**
|
|
3777
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
3778
|
+
*
|
|
3779
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
3780
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
3781
|
+
* - clean → 201, video record created with status='uploading',
|
|
3782
|
+
* transcode worker advances on `scan.file.completed`
|
|
3783
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
3784
|
+
* worker advances when scan completes
|
|
3785
|
+
* - threat → 409 (rejected; row not created)
|
|
3786
|
+
*
|
|
3787
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
3788
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
3789
|
+
*
|
|
3790
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
3791
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
3792
|
+
* `getStreamUrl()` / `get()`.
|
|
3793
|
+
*
|
|
3794
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
3795
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
3796
|
+
*/
|
|
3797
|
+
async register(request, options) {
|
|
3798
|
+
return this.post(
|
|
3799
|
+
"/register",
|
|
3800
|
+
{
|
|
3801
|
+
file_id: request.fileId,
|
|
3802
|
+
sm_user_id: request.userId
|
|
3803
|
+
},
|
|
3804
|
+
options
|
|
3805
|
+
);
|
|
3806
|
+
}
|
|
3807
|
+
/**
|
|
3808
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
3809
|
+
* compression) and register it with the video service so transcoding
|
|
3810
|
+
* + HLS streaming work.
|
|
3811
|
+
*
|
|
3812
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
3813
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
3814
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
3815
|
+
* once the transcoder finishes.
|
|
3816
|
+
*
|
|
3817
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
3818
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
3819
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
3820
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
3821
|
+
*
|
|
3822
|
+
* If `register()` fails after a successful storage upload, the file
|
|
3823
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
3824
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
3825
|
+
* to `null`.
|
|
3826
|
+
*/
|
|
3827
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
3828
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
3829
|
+
filename: uploadOptions?.filename,
|
|
3830
|
+
metadata: uploadOptions?.metadata,
|
|
3831
|
+
onProgress: uploadOptions?.onProgress,
|
|
3832
|
+
signal: uploadOptions?.signal
|
|
3833
|
+
});
|
|
3834
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
3835
|
+
return { data: null, error: uploadResult.error };
|
|
3836
|
+
}
|
|
3837
|
+
const fileInfo = uploadResult.data;
|
|
3838
|
+
const fileId = fileInfo.id;
|
|
3839
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
3840
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
3841
|
+
if (registerResult.error || !registerResult.data) {
|
|
3842
|
+
console.warn(
|
|
3843
|
+
"[scalemule-sdk] video.register() failed after storage upload; HLS variants unavailable.",
|
|
3844
|
+
registerResult.error
|
|
3845
|
+
);
|
|
3846
|
+
return {
|
|
3847
|
+
data: {
|
|
3848
|
+
file_id: fileId,
|
|
3849
|
+
video_id: fileId,
|
|
3850
|
+
original_view_url: originalViewUrl,
|
|
3851
|
+
hls_url_promise: Promise.resolve(null)
|
|
3852
|
+
},
|
|
3853
|
+
error: null
|
|
3854
|
+
};
|
|
3855
|
+
}
|
|
3856
|
+
const videoId = registerResult.data.video_id;
|
|
3857
|
+
const hlsUrlPromise = this.pollTranscodeComplete(videoId, requestOptions);
|
|
3858
|
+
return {
|
|
3859
|
+
data: {
|
|
3860
|
+
file_id: fileId,
|
|
3861
|
+
video_id: videoId,
|
|
3862
|
+
original_view_url: originalViewUrl,
|
|
3863
|
+
hls_url_promise: hlsUrlPromise
|
|
3864
|
+
},
|
|
3865
|
+
error: null
|
|
3866
|
+
};
|
|
3867
|
+
}
|
|
3868
|
+
/**
|
|
3869
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
3870
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
3871
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
3872
|
+
*/
|
|
3873
|
+
async pollTranscodeComplete(videoId, requestOptions) {
|
|
3874
|
+
const intervalMs = 1e3;
|
|
3875
|
+
const maxAttempts = 30;
|
|
3876
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
3877
|
+
const result = await this.get(videoId, requestOptions);
|
|
3878
|
+
if (result.data?.status === "ready") {
|
|
3879
|
+
return `${this.client.getBaseUrl()}${this.basePath}/${videoId}/playlist.m3u8`;
|
|
3880
|
+
}
|
|
3881
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
3882
|
+
}
|
|
3883
|
+
return null;
|
|
3884
|
+
}
|
|
3737
3885
|
/**
|
|
3738
3886
|
* Get the HLS master playlist URL for streaming.
|
|
3739
3887
|
* Returns the playlist URL that can be passed to a video player.
|
|
@@ -5670,8 +5818,14 @@ var SearchService = class extends ServiceModule {
|
|
|
5670
5818
|
// src/services/photo.ts
|
|
5671
5819
|
var PHOTO_BREAKPOINTS = [36, 150, 320, 640, 1080];
|
|
5672
5820
|
var PhotoService = class extends ServiceModule {
|
|
5673
|
-
|
|
5674
|
-
|
|
5821
|
+
/**
|
|
5822
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
5823
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
5824
|
+
* instantiate `PhotoService` directly.
|
|
5825
|
+
*/
|
|
5826
|
+
constructor(client, storage) {
|
|
5827
|
+
super(client);
|
|
5828
|
+
this.storage = storage;
|
|
5675
5829
|
this.basePath = "/v1/photos";
|
|
5676
5830
|
}
|
|
5677
5831
|
async upload(file, uploadOptions, requestOptions) {
|
|
@@ -5811,6 +5965,87 @@ var PhotoService = class extends ServiceModule {
|
|
|
5811
5965
|
}
|
|
5812
5966
|
};
|
|
5813
5967
|
}
|
|
5968
|
+
/**
|
|
5969
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
5970
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
5971
|
+
*
|
|
5972
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
5973
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
5974
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
5975
|
+
* usable URLs.
|
|
5976
|
+
*
|
|
5977
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
5978
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
5979
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
5980
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
5981
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
5982
|
+
* subscription.
|
|
5983
|
+
*
|
|
5984
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
5985
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
5986
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
5987
|
+
* `optimized_url_promise` to `null`.
|
|
5988
|
+
*/
|
|
5989
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
5990
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
5991
|
+
filename: uploadOptions?.filename,
|
|
5992
|
+
metadata: uploadOptions?.metadata,
|
|
5993
|
+
onProgress: uploadOptions?.onProgress,
|
|
5994
|
+
signal: uploadOptions?.signal
|
|
5995
|
+
});
|
|
5996
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
5997
|
+
return { data: null, error: uploadResult.error };
|
|
5998
|
+
}
|
|
5999
|
+
const fileInfo = uploadResult.data;
|
|
6000
|
+
const fileId = fileInfo.id;
|
|
6001
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
6002
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
6003
|
+
if (registerResult.error || !registerResult.data) {
|
|
6004
|
+
console.warn(
|
|
6005
|
+
"[scalemule-sdk] photo.register() failed after storage upload; optimized variants unavailable.",
|
|
6006
|
+
registerResult.error
|
|
6007
|
+
);
|
|
6008
|
+
return {
|
|
6009
|
+
data: {
|
|
6010
|
+
file_id: fileId,
|
|
6011
|
+
photo_id: null,
|
|
6012
|
+
original_view_url: originalViewUrl,
|
|
6013
|
+
optimized_url_promise: Promise.resolve(null)
|
|
6014
|
+
},
|
|
6015
|
+
error: null
|
|
6016
|
+
};
|
|
6017
|
+
}
|
|
6018
|
+
const photoId = registerResult.data.id;
|
|
6019
|
+
const optimizedUrlPromise = this.pollOptimizationComplete(photoId, requestOptions);
|
|
6020
|
+
return {
|
|
6021
|
+
data: {
|
|
6022
|
+
file_id: fileId,
|
|
6023
|
+
photo_id: photoId,
|
|
6024
|
+
original_view_url: originalViewUrl,
|
|
6025
|
+
optimized_url_promise: optimizedUrlPromise
|
|
6026
|
+
},
|
|
6027
|
+
error: null
|
|
6028
|
+
};
|
|
6029
|
+
}
|
|
6030
|
+
/**
|
|
6031
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
6032
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
6033
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
6034
|
+
* which uses the on-demand transform path).
|
|
6035
|
+
*/
|
|
6036
|
+
async pollOptimizationComplete(photoId, requestOptions) {
|
|
6037
|
+
const intervalMs = 250;
|
|
6038
|
+
const maxAttempts = 40;
|
|
6039
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
6040
|
+
const result = await this.get(photoId, requestOptions);
|
|
6041
|
+
const status = result.data?.optimization_status;
|
|
6042
|
+
if (status === "completed") {
|
|
6043
|
+
return this.getOptimalUrl(photoId, 1080);
|
|
6044
|
+
}
|
|
6045
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
6046
|
+
}
|
|
6047
|
+
return null;
|
|
6048
|
+
}
|
|
5814
6049
|
/** @deprecated Use upload() instead */
|
|
5815
6050
|
async uploadPhoto(file, options) {
|
|
5816
6051
|
return this.upload(file, options);
|
|
@@ -6647,7 +6882,7 @@ var ScaleMule = class {
|
|
|
6647
6882
|
this.auth = new AuthService(this._client);
|
|
6648
6883
|
this.storage = new StorageService(this._client);
|
|
6649
6884
|
this.realtime = new RealtimeService(this._client);
|
|
6650
|
-
this.video = new VideoService(this._client);
|
|
6885
|
+
this.video = new VideoService(this._client, this.storage);
|
|
6651
6886
|
this.data = new DataService(this._client);
|
|
6652
6887
|
this.chat = new ChatService(this._client);
|
|
6653
6888
|
this.conference = new ConferenceService(this._client);
|
|
@@ -6674,7 +6909,7 @@ var ScaleMule = class {
|
|
|
6674
6909
|
this.events = new EventsService(this._client);
|
|
6675
6910
|
this.graph = new GraphService(this._client);
|
|
6676
6911
|
this.functions = new FunctionsService(this._client);
|
|
6677
|
-
this.photo = new PhotoService(this._client);
|
|
6912
|
+
this.photo = new PhotoService(this._client, this.storage);
|
|
6678
6913
|
this.flagContent = new FlagContentService(this._client);
|
|
6679
6914
|
this.creatorMaker = new CreatorMakerService(this._client);
|
|
6680
6915
|
this.compliance = new ComplianceService(this._client);
|