@scalemule/sdk 0.0.38 → 0.0.40
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 +150 -0
- package/dist/index.d.ts +150 -0
- package/dist/index.js +142 -3
- package/dist/index.mjs +142 -3
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -1122,6 +1122,39 @@ interface SignedUrlResponse {
|
|
|
1122
1122
|
url: string;
|
|
1123
1123
|
expires_at: string;
|
|
1124
1124
|
}
|
|
1125
|
+
/**
|
|
1126
|
+
* Aggregate file status — returned by {@link StorageService.getFileStatus}.
|
|
1127
|
+
*
|
|
1128
|
+
* Foundational primitive for the chat / progressive media read side.
|
|
1129
|
+
* `optimize` and `transcode` are reserved for Phase 3 enrichment; until
|
|
1130
|
+
* filled, callers should attempt the constructed `urls.optimized` /
|
|
1131
|
+
* `urls.hls` directly (404 means pipeline still running).
|
|
1132
|
+
*/
|
|
1133
|
+
interface FileStatus {
|
|
1134
|
+
file_id: string;
|
|
1135
|
+
mime_type: string;
|
|
1136
|
+
scan: {
|
|
1137
|
+
/** pending | scanning | clean | threat | error | quarantined */
|
|
1138
|
+
status: string;
|
|
1139
|
+
scanned_at?: string;
|
|
1140
|
+
};
|
|
1141
|
+
optimize: {
|
|
1142
|
+
status: string;
|
|
1143
|
+
breakpoints?: number[];
|
|
1144
|
+
} | null;
|
|
1145
|
+
transcode: {
|
|
1146
|
+
status: string;
|
|
1147
|
+
manifest_url?: string;
|
|
1148
|
+
} | null;
|
|
1149
|
+
urls: {
|
|
1150
|
+
/** Gateway path for the original bytes — `/v1/storage/files/{id}` */
|
|
1151
|
+
original: string;
|
|
1152
|
+
/** Gateway path for the photo transform — image MIME types only */
|
|
1153
|
+
optimized?: string;
|
|
1154
|
+
/** Gateway path for the HLS master playlist — video MIME types only */
|
|
1155
|
+
hls?: string;
|
|
1156
|
+
};
|
|
1157
|
+
}
|
|
1125
1158
|
declare class StorageService extends ServiceModule {
|
|
1126
1159
|
protected basePath: string;
|
|
1127
1160
|
private telemetry;
|
|
@@ -1207,6 +1240,29 @@ declare class StorageService extends ServiceModule {
|
|
|
1207
1240
|
}>>;
|
|
1208
1241
|
/** Get file metadata (no signed URL). */
|
|
1209
1242
|
getInfo(fileId: string, options?: RequestOptions): Promise<ApiResponse<FileInfo>>;
|
|
1243
|
+
/**
|
|
1244
|
+
* Aggregate status for a file — single call returns scan + reserved
|
|
1245
|
+
* optimize/transcode slots + the canonical view URL paths for image
|
|
1246
|
+
* (transform endpoint) and video (HLS playlist) MIME types.
|
|
1247
|
+
*
|
|
1248
|
+
* Foundational primitive for the chat / progressive media read side.
|
|
1249
|
+
* `useFileStatus()` (in `@scalemule/nextjs`) consumes this for both
|
|
1250
|
+
* first-paint and refresh-on-demand scenarios.
|
|
1251
|
+
*
|
|
1252
|
+
* `optimize` and `transcode` are reserved for Phase 3 enrichment. Until
|
|
1253
|
+
* the photo/video services expose internal status endpoints, callers
|
|
1254
|
+
* should attempt the constructed URLs directly to discover readiness
|
|
1255
|
+
* (404 means the pipeline is still running).
|
|
1256
|
+
*
|
|
1257
|
+
* @example
|
|
1258
|
+
* ```ts
|
|
1259
|
+
* const r = await client.storage.getFileStatus(fileId);
|
|
1260
|
+
* if (r.data?.scan.status === 'clean' && r.data.urls.optimized) {
|
|
1261
|
+
* // image: try transform URL for an optimized variant
|
|
1262
|
+
* }
|
|
1263
|
+
* ```
|
|
1264
|
+
*/
|
|
1265
|
+
getFileStatus(fileId: string, options?: RequestOptions): Promise<ApiResponse<FileStatus>>;
|
|
1210
1266
|
/**
|
|
1211
1267
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
1212
1268
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
|
@@ -1691,8 +1747,47 @@ interface VideoInfo {
|
|
|
1691
1747
|
created_at: string;
|
|
1692
1748
|
updated_at: string;
|
|
1693
1749
|
}
|
|
1750
|
+
/** Request body for {@link VideoService.register}. */
|
|
1751
|
+
interface RegisterVideoRequest {
|
|
1752
|
+
/** Storage file_id of the previously-uploaded video. */
|
|
1753
|
+
fileId: string;
|
|
1754
|
+
/** Optional override; defaults to the gateway-injected x-user-id. */
|
|
1755
|
+
userId?: string;
|
|
1756
|
+
}
|
|
1757
|
+
/** Response shape from POST /v1/videos/register. */
|
|
1758
|
+
interface RegisterVideoResponse {
|
|
1759
|
+
video_id: string;
|
|
1760
|
+
file_id: string;
|
|
1761
|
+
/** `registering` (scan was clean) | `pending_scan` (scan in progress) */
|
|
1762
|
+
status: 'registering' | 'pending_scan';
|
|
1763
|
+
original_view_url: string;
|
|
1764
|
+
}
|
|
1765
|
+
/** Result of {@link VideoService.uploadViaStorage}. */
|
|
1766
|
+
interface VideoUploadViaStorageResult {
|
|
1767
|
+
/** Storage file_id — store this in chat-attachment metadata. */
|
|
1768
|
+
file_id: string;
|
|
1769
|
+
/** Video service id. Equals `file_id` for storage-backed videos. */
|
|
1770
|
+
video_id: string;
|
|
1771
|
+
/**
|
|
1772
|
+
* Short-lived signed URL to the original bytes. Usable immediately on the
|
|
1773
|
+
* recipient side, before HLS transcoding completes.
|
|
1774
|
+
*/
|
|
1775
|
+
original_view_url: string | null;
|
|
1776
|
+
/**
|
|
1777
|
+
* Resolves once the transcode worker finishes (or times out at 30s).
|
|
1778
|
+
* On resolution: an HLS master playlist URL. On timeout: `null` — caller
|
|
1779
|
+
* should fall back to `original_view_url` and try the playlist later.
|
|
1780
|
+
*/
|
|
1781
|
+
hls_url_promise: Promise<string | null>;
|
|
1782
|
+
}
|
|
1694
1783
|
declare class VideoService extends ServiceModule {
|
|
1784
|
+
private readonly storage;
|
|
1695
1785
|
protected basePath: string;
|
|
1786
|
+
/**
|
|
1787
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
1788
|
+
* top-level {@link ScaleMule} constructor.
|
|
1789
|
+
*/
|
|
1790
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
1696
1791
|
/**
|
|
1697
1792
|
* Upload a video file using chunked multipart upload.
|
|
1698
1793
|
*
|
|
@@ -1706,6 +1801,61 @@ declare class VideoService extends ServiceModule {
|
|
|
1706
1801
|
upload(file: File | Blob, options?: VideoUploadOptions, requestOptions?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1707
1802
|
/** Get video metadata and status. */
|
|
1708
1803
|
get(videoId: string, options?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1804
|
+
/**
|
|
1805
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
1806
|
+
*
|
|
1807
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
1808
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
1809
|
+
* - clean → 201, video record created with status='uploading',
|
|
1810
|
+
* transcode worker advances on `scan.file.completed`
|
|
1811
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
1812
|
+
* worker advances when scan completes
|
|
1813
|
+
* - threat → 409 (rejected; row not created)
|
|
1814
|
+
*
|
|
1815
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
1816
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
1817
|
+
*
|
|
1818
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
1819
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
1820
|
+
* `getStreamUrl()` / `get()`.
|
|
1821
|
+
*
|
|
1822
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
1823
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
1824
|
+
*/
|
|
1825
|
+
register(request: RegisterVideoRequest, options?: RequestOptions): Promise<ApiResponse<RegisterVideoResponse>>;
|
|
1826
|
+
/**
|
|
1827
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
1828
|
+
* compression) and register it with the video service so transcoding
|
|
1829
|
+
* + HLS streaming work.
|
|
1830
|
+
*
|
|
1831
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
1832
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
1833
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
1834
|
+
* once the transcoder finishes.
|
|
1835
|
+
*
|
|
1836
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
1837
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
1838
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
1839
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
1840
|
+
*
|
|
1841
|
+
* If `register()` fails after a successful storage upload, the file
|
|
1842
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
1843
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
1844
|
+
* to `null`.
|
|
1845
|
+
*/
|
|
1846
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
1847
|
+
userId?: string;
|
|
1848
|
+
filename?: string;
|
|
1849
|
+
metadata?: Record<string, unknown>;
|
|
1850
|
+
onProgress?: (progress: number) => void;
|
|
1851
|
+
signal?: AbortSignal;
|
|
1852
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<VideoUploadViaStorageResult>>;
|
|
1853
|
+
/**
|
|
1854
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
1855
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
1856
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
1857
|
+
*/
|
|
1858
|
+
private pollTranscodeComplete;
|
|
1709
1859
|
/**
|
|
1710
1860
|
* Get the HLS master playlist URL for streaming.
|
|
1711
1861
|
* Returns the playlist URL that can be passed to a video player.
|
package/dist/index.d.ts
CHANGED
|
@@ -1122,6 +1122,39 @@ interface SignedUrlResponse {
|
|
|
1122
1122
|
url: string;
|
|
1123
1123
|
expires_at: string;
|
|
1124
1124
|
}
|
|
1125
|
+
/**
|
|
1126
|
+
* Aggregate file status — returned by {@link StorageService.getFileStatus}.
|
|
1127
|
+
*
|
|
1128
|
+
* Foundational primitive for the chat / progressive media read side.
|
|
1129
|
+
* `optimize` and `transcode` are reserved for Phase 3 enrichment; until
|
|
1130
|
+
* filled, callers should attempt the constructed `urls.optimized` /
|
|
1131
|
+
* `urls.hls` directly (404 means pipeline still running).
|
|
1132
|
+
*/
|
|
1133
|
+
interface FileStatus {
|
|
1134
|
+
file_id: string;
|
|
1135
|
+
mime_type: string;
|
|
1136
|
+
scan: {
|
|
1137
|
+
/** pending | scanning | clean | threat | error | quarantined */
|
|
1138
|
+
status: string;
|
|
1139
|
+
scanned_at?: string;
|
|
1140
|
+
};
|
|
1141
|
+
optimize: {
|
|
1142
|
+
status: string;
|
|
1143
|
+
breakpoints?: number[];
|
|
1144
|
+
} | null;
|
|
1145
|
+
transcode: {
|
|
1146
|
+
status: string;
|
|
1147
|
+
manifest_url?: string;
|
|
1148
|
+
} | null;
|
|
1149
|
+
urls: {
|
|
1150
|
+
/** Gateway path for the original bytes — `/v1/storage/files/{id}` */
|
|
1151
|
+
original: string;
|
|
1152
|
+
/** Gateway path for the photo transform — image MIME types only */
|
|
1153
|
+
optimized?: string;
|
|
1154
|
+
/** Gateway path for the HLS master playlist — video MIME types only */
|
|
1155
|
+
hls?: string;
|
|
1156
|
+
};
|
|
1157
|
+
}
|
|
1125
1158
|
declare class StorageService extends ServiceModule {
|
|
1126
1159
|
protected basePath: string;
|
|
1127
1160
|
private telemetry;
|
|
@@ -1207,6 +1240,29 @@ declare class StorageService extends ServiceModule {
|
|
|
1207
1240
|
}>>;
|
|
1208
1241
|
/** Get file metadata (no signed URL). */
|
|
1209
1242
|
getInfo(fileId: string, options?: RequestOptions): Promise<ApiResponse<FileInfo>>;
|
|
1243
|
+
/**
|
|
1244
|
+
* Aggregate status for a file — single call returns scan + reserved
|
|
1245
|
+
* optimize/transcode slots + the canonical view URL paths for image
|
|
1246
|
+
* (transform endpoint) and video (HLS playlist) MIME types.
|
|
1247
|
+
*
|
|
1248
|
+
* Foundational primitive for the chat / progressive media read side.
|
|
1249
|
+
* `useFileStatus()` (in `@scalemule/nextjs`) consumes this for both
|
|
1250
|
+
* first-paint and refresh-on-demand scenarios.
|
|
1251
|
+
*
|
|
1252
|
+
* `optimize` and `transcode` are reserved for Phase 3 enrichment. Until
|
|
1253
|
+
* the photo/video services expose internal status endpoints, callers
|
|
1254
|
+
* should attempt the constructed URLs directly to discover readiness
|
|
1255
|
+
* (404 means the pipeline is still running).
|
|
1256
|
+
*
|
|
1257
|
+
* @example
|
|
1258
|
+
* ```ts
|
|
1259
|
+
* const r = await client.storage.getFileStatus(fileId);
|
|
1260
|
+
* if (r.data?.scan.status === 'clean' && r.data.urls.optimized) {
|
|
1261
|
+
* // image: try transform URL for an optimized variant
|
|
1262
|
+
* }
|
|
1263
|
+
* ```
|
|
1264
|
+
*/
|
|
1265
|
+
getFileStatus(fileId: string, options?: RequestOptions): Promise<ApiResponse<FileStatus>>;
|
|
1210
1266
|
/**
|
|
1211
1267
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
1212
1268
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
|
@@ -1691,8 +1747,47 @@ interface VideoInfo {
|
|
|
1691
1747
|
created_at: string;
|
|
1692
1748
|
updated_at: string;
|
|
1693
1749
|
}
|
|
1750
|
+
/** Request body for {@link VideoService.register}. */
|
|
1751
|
+
interface RegisterVideoRequest {
|
|
1752
|
+
/** Storage file_id of the previously-uploaded video. */
|
|
1753
|
+
fileId: string;
|
|
1754
|
+
/** Optional override; defaults to the gateway-injected x-user-id. */
|
|
1755
|
+
userId?: string;
|
|
1756
|
+
}
|
|
1757
|
+
/** Response shape from POST /v1/videos/register. */
|
|
1758
|
+
interface RegisterVideoResponse {
|
|
1759
|
+
video_id: string;
|
|
1760
|
+
file_id: string;
|
|
1761
|
+
/** `registering` (scan was clean) | `pending_scan` (scan in progress) */
|
|
1762
|
+
status: 'registering' | 'pending_scan';
|
|
1763
|
+
original_view_url: string;
|
|
1764
|
+
}
|
|
1765
|
+
/** Result of {@link VideoService.uploadViaStorage}. */
|
|
1766
|
+
interface VideoUploadViaStorageResult {
|
|
1767
|
+
/** Storage file_id — store this in chat-attachment metadata. */
|
|
1768
|
+
file_id: string;
|
|
1769
|
+
/** Video service id. Equals `file_id` for storage-backed videos. */
|
|
1770
|
+
video_id: string;
|
|
1771
|
+
/**
|
|
1772
|
+
* Short-lived signed URL to the original bytes. Usable immediately on the
|
|
1773
|
+
* recipient side, before HLS transcoding completes.
|
|
1774
|
+
*/
|
|
1775
|
+
original_view_url: string | null;
|
|
1776
|
+
/**
|
|
1777
|
+
* Resolves once the transcode worker finishes (or times out at 30s).
|
|
1778
|
+
* On resolution: an HLS master playlist URL. On timeout: `null` — caller
|
|
1779
|
+
* should fall back to `original_view_url` and try the playlist later.
|
|
1780
|
+
*/
|
|
1781
|
+
hls_url_promise: Promise<string | null>;
|
|
1782
|
+
}
|
|
1694
1783
|
declare class VideoService extends ServiceModule {
|
|
1784
|
+
private readonly storage;
|
|
1695
1785
|
protected basePath: string;
|
|
1786
|
+
/**
|
|
1787
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
1788
|
+
* top-level {@link ScaleMule} constructor.
|
|
1789
|
+
*/
|
|
1790
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
1696
1791
|
/**
|
|
1697
1792
|
* Upload a video file using chunked multipart upload.
|
|
1698
1793
|
*
|
|
@@ -1706,6 +1801,61 @@ declare class VideoService extends ServiceModule {
|
|
|
1706
1801
|
upload(file: File | Blob, options?: VideoUploadOptions, requestOptions?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1707
1802
|
/** Get video metadata and status. */
|
|
1708
1803
|
get(videoId: string, options?: RequestOptions): Promise<ApiResponse<VideoInfo>>;
|
|
1804
|
+
/**
|
|
1805
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
1806
|
+
*
|
|
1807
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
1808
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
1809
|
+
* - clean → 201, video record created with status='uploading',
|
|
1810
|
+
* transcode worker advances on `scan.file.completed`
|
|
1811
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
1812
|
+
* worker advances when scan completes
|
|
1813
|
+
* - threat → 409 (rejected; row not created)
|
|
1814
|
+
*
|
|
1815
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
1816
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
1817
|
+
*
|
|
1818
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
1819
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
1820
|
+
* `getStreamUrl()` / `get()`.
|
|
1821
|
+
*
|
|
1822
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
1823
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
1824
|
+
*/
|
|
1825
|
+
register(request: RegisterVideoRequest, options?: RequestOptions): Promise<ApiResponse<RegisterVideoResponse>>;
|
|
1826
|
+
/**
|
|
1827
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
1828
|
+
* compression) and register it with the video service so transcoding
|
|
1829
|
+
* + HLS streaming work.
|
|
1830
|
+
*
|
|
1831
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
1832
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
1833
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
1834
|
+
* once the transcoder finishes.
|
|
1835
|
+
*
|
|
1836
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
1837
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
1838
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
1839
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
1840
|
+
*
|
|
1841
|
+
* If `register()` fails after a successful storage upload, the file
|
|
1842
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
1843
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
1844
|
+
* to `null`.
|
|
1845
|
+
*/
|
|
1846
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
1847
|
+
userId?: string;
|
|
1848
|
+
filename?: string;
|
|
1849
|
+
metadata?: Record<string, unknown>;
|
|
1850
|
+
onProgress?: (progress: number) => void;
|
|
1851
|
+
signal?: AbortSignal;
|
|
1852
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<VideoUploadViaStorageResult>>;
|
|
1853
|
+
/**
|
|
1854
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
1855
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
1856
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
1857
|
+
*/
|
|
1858
|
+
private pollTranscodeComplete;
|
|
1709
1859
|
/**
|
|
1710
1860
|
* Get the HLS master playlist URL for streaming.
|
|
1711
1861
|
* Returns the playlist URL that can be passed to a video player.
|
package/dist/index.js
CHANGED
|
@@ -2943,6 +2943,31 @@ var StorageService = class extends ServiceModule {
|
|
|
2943
2943
|
async getInfo(fileId, options) {
|
|
2944
2944
|
return this._get(`/files/${fileId}/info`, options);
|
|
2945
2945
|
}
|
|
2946
|
+
/**
|
|
2947
|
+
* Aggregate status for a file — single call returns scan + reserved
|
|
2948
|
+
* optimize/transcode slots + the canonical view URL paths for image
|
|
2949
|
+
* (transform endpoint) and video (HLS playlist) MIME types.
|
|
2950
|
+
*
|
|
2951
|
+
* Foundational primitive for the chat / progressive media read side.
|
|
2952
|
+
* `useFileStatus()` (in `@scalemule/nextjs`) consumes this for both
|
|
2953
|
+
* first-paint and refresh-on-demand scenarios.
|
|
2954
|
+
*
|
|
2955
|
+
* `optimize` and `transcode` are reserved for Phase 3 enrichment. Until
|
|
2956
|
+
* the photo/video services expose internal status endpoints, callers
|
|
2957
|
+
* should attempt the constructed URLs directly to discover readiness
|
|
2958
|
+
* (404 means the pipeline is still running).
|
|
2959
|
+
*
|
|
2960
|
+
* @example
|
|
2961
|
+
* ```ts
|
|
2962
|
+
* const r = await client.storage.getFileStatus(fileId);
|
|
2963
|
+
* if (r.data?.scan.status === 'clean' && r.data.urls.optimized) {
|
|
2964
|
+
* // image: try transform URL for an optimized variant
|
|
2965
|
+
* }
|
|
2966
|
+
* ```
|
|
2967
|
+
*/
|
|
2968
|
+
async getFileStatus(fileId, options) {
|
|
2969
|
+
return this._get(`/files/${fileId}/status`, options);
|
|
2970
|
+
}
|
|
2946
2971
|
/**
|
|
2947
2972
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
2948
2973
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
|
@@ -4065,8 +4090,13 @@ var RealtimeService = class extends ServiceModule {
|
|
|
4065
4090
|
var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
4066
4091
|
var MIN_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
4067
4092
|
var VideoService = class extends ServiceModule {
|
|
4068
|
-
|
|
4069
|
-
|
|
4093
|
+
/**
|
|
4094
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
4095
|
+
* top-level {@link ScaleMule} constructor.
|
|
4096
|
+
*/
|
|
4097
|
+
constructor(client, storage) {
|
|
4098
|
+
super(client);
|
|
4099
|
+
this.storage = storage;
|
|
4070
4100
|
this.basePath = "/v1/videos";
|
|
4071
4101
|
}
|
|
4072
4102
|
// --------------------------------------------------------------------------
|
|
@@ -4140,6 +4170,115 @@ var VideoService = class extends ServiceModule {
|
|
|
4140
4170
|
async get(videoId, options) {
|
|
4141
4171
|
return super._get(`/${videoId}`, options);
|
|
4142
4172
|
}
|
|
4173
|
+
/**
|
|
4174
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
4175
|
+
*
|
|
4176
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
4177
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
4178
|
+
* - clean → 201, video record created with status='uploading',
|
|
4179
|
+
* transcode worker advances on `scan.file.completed`
|
|
4180
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
4181
|
+
* worker advances when scan completes
|
|
4182
|
+
* - threat → 409 (rejected; row not created)
|
|
4183
|
+
*
|
|
4184
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
4185
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
4186
|
+
*
|
|
4187
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
4188
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
4189
|
+
* `getStreamUrl()` / `get()`.
|
|
4190
|
+
*
|
|
4191
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
4192
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
4193
|
+
*/
|
|
4194
|
+
async register(request, options) {
|
|
4195
|
+
return this.post(
|
|
4196
|
+
"/register",
|
|
4197
|
+
{
|
|
4198
|
+
file_id: request.fileId,
|
|
4199
|
+
sm_user_id: request.userId
|
|
4200
|
+
},
|
|
4201
|
+
options
|
|
4202
|
+
);
|
|
4203
|
+
}
|
|
4204
|
+
/**
|
|
4205
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
4206
|
+
* compression) and register it with the video service so transcoding
|
|
4207
|
+
* + HLS streaming work.
|
|
4208
|
+
*
|
|
4209
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
4210
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
4211
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
4212
|
+
* once the transcoder finishes.
|
|
4213
|
+
*
|
|
4214
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
4215
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
4216
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
4217
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
4218
|
+
*
|
|
4219
|
+
* If `register()` fails after a successful storage upload, the file
|
|
4220
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
4221
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
4222
|
+
* to `null`.
|
|
4223
|
+
*/
|
|
4224
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
4225
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
4226
|
+
filename: uploadOptions?.filename,
|
|
4227
|
+
metadata: uploadOptions?.metadata,
|
|
4228
|
+
onProgress: uploadOptions?.onProgress,
|
|
4229
|
+
signal: uploadOptions?.signal
|
|
4230
|
+
});
|
|
4231
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
4232
|
+
return { data: null, error: uploadResult.error };
|
|
4233
|
+
}
|
|
4234
|
+
const fileInfo = uploadResult.data;
|
|
4235
|
+
const fileId = fileInfo.id;
|
|
4236
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
4237
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
4238
|
+
if (registerResult.error || !registerResult.data) {
|
|
4239
|
+
console.warn(
|
|
4240
|
+
"[scalemule-sdk] video.register() failed after storage upload; HLS variants unavailable.",
|
|
4241
|
+
registerResult.error
|
|
4242
|
+
);
|
|
4243
|
+
return {
|
|
4244
|
+
data: {
|
|
4245
|
+
file_id: fileId,
|
|
4246
|
+
video_id: fileId,
|
|
4247
|
+
original_view_url: originalViewUrl,
|
|
4248
|
+
hls_url_promise: Promise.resolve(null)
|
|
4249
|
+
},
|
|
4250
|
+
error: null
|
|
4251
|
+
};
|
|
4252
|
+
}
|
|
4253
|
+
const videoId = registerResult.data.video_id;
|
|
4254
|
+
const hlsUrlPromise = this.pollTranscodeComplete(videoId, requestOptions);
|
|
4255
|
+
return {
|
|
4256
|
+
data: {
|
|
4257
|
+
file_id: fileId,
|
|
4258
|
+
video_id: videoId,
|
|
4259
|
+
original_view_url: originalViewUrl,
|
|
4260
|
+
hls_url_promise: hlsUrlPromise
|
|
4261
|
+
},
|
|
4262
|
+
error: null
|
|
4263
|
+
};
|
|
4264
|
+
}
|
|
4265
|
+
/**
|
|
4266
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
4267
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
4268
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
4269
|
+
*/
|
|
4270
|
+
async pollTranscodeComplete(videoId, requestOptions) {
|
|
4271
|
+
const intervalMs = 1e3;
|
|
4272
|
+
const maxAttempts = 30;
|
|
4273
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
4274
|
+
const result = await this.get(videoId, requestOptions);
|
|
4275
|
+
if (result.data?.status === "ready") {
|
|
4276
|
+
return `${this.client.getBaseUrl()}${this.basePath}/${videoId}/playlist.m3u8`;
|
|
4277
|
+
}
|
|
4278
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
4279
|
+
}
|
|
4280
|
+
return null;
|
|
4281
|
+
}
|
|
4143
4282
|
/**
|
|
4144
4283
|
* Get the HLS master playlist URL for streaming.
|
|
4145
4284
|
* Returns the playlist URL that can be passed to a video player.
|
|
@@ -7140,7 +7279,7 @@ var ScaleMule = class {
|
|
|
7140
7279
|
this.auth = new AuthService(this._client);
|
|
7141
7280
|
this.storage = new StorageService(this._client);
|
|
7142
7281
|
this.realtime = new RealtimeService(this._client);
|
|
7143
|
-
this.video = new VideoService(this._client);
|
|
7282
|
+
this.video = new VideoService(this._client, this.storage);
|
|
7144
7283
|
this.data = new DataService(this._client);
|
|
7145
7284
|
this.chat = new ChatService(this._client);
|
|
7146
7285
|
this.conference = new ConferenceService(this._client);
|
package/dist/index.mjs
CHANGED
|
@@ -2574,6 +2574,31 @@ var StorageService = class extends ServiceModule {
|
|
|
2574
2574
|
async getInfo(fileId, options) {
|
|
2575
2575
|
return this._get(`/files/${fileId}/info`, options);
|
|
2576
2576
|
}
|
|
2577
|
+
/**
|
|
2578
|
+
* Aggregate status for a file — single call returns scan + reserved
|
|
2579
|
+
* optimize/transcode slots + the canonical view URL paths for image
|
|
2580
|
+
* (transform endpoint) and video (HLS playlist) MIME types.
|
|
2581
|
+
*
|
|
2582
|
+
* Foundational primitive for the chat / progressive media read side.
|
|
2583
|
+
* `useFileStatus()` (in `@scalemule/nextjs`) consumes this for both
|
|
2584
|
+
* first-paint and refresh-on-demand scenarios.
|
|
2585
|
+
*
|
|
2586
|
+
* `optimize` and `transcode` are reserved for Phase 3 enrichment. Until
|
|
2587
|
+
* the photo/video services expose internal status endpoints, callers
|
|
2588
|
+
* should attempt the constructed URLs directly to discover readiness
|
|
2589
|
+
* (404 means the pipeline is still running).
|
|
2590
|
+
*
|
|
2591
|
+
* @example
|
|
2592
|
+
* ```ts
|
|
2593
|
+
* const r = await client.storage.getFileStatus(fileId);
|
|
2594
|
+
* if (r.data?.scan.status === 'clean' && r.data.urls.optimized) {
|
|
2595
|
+
* // image: try transform URL for an optimized variant
|
|
2596
|
+
* }
|
|
2597
|
+
* ```
|
|
2598
|
+
*/
|
|
2599
|
+
async getFileStatus(fileId, options) {
|
|
2600
|
+
return this._get(`/files/${fileId}/status`, options);
|
|
2601
|
+
}
|
|
2577
2602
|
/**
|
|
2578
2603
|
* Get a signed view URL for inline display (img src, thumbnails).
|
|
2579
2604
|
* Returns CloudFront signed URL (fast, ~1us) or S3 presigned fallback.
|
|
@@ -3693,8 +3718,13 @@ var RealtimeService = class extends ServiceModule {
|
|
|
3693
3718
|
var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
3694
3719
|
var MIN_CHUNK_SIZE = 5 * 1024 * 1024;
|
|
3695
3720
|
var VideoService = class extends ServiceModule {
|
|
3696
|
-
|
|
3697
|
-
|
|
3721
|
+
/**
|
|
3722
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
3723
|
+
* top-level {@link ScaleMule} constructor.
|
|
3724
|
+
*/
|
|
3725
|
+
constructor(client, storage) {
|
|
3726
|
+
super(client);
|
|
3727
|
+
this.storage = storage;
|
|
3698
3728
|
this.basePath = "/v1/videos";
|
|
3699
3729
|
}
|
|
3700
3730
|
// --------------------------------------------------------------------------
|
|
@@ -3768,6 +3798,115 @@ var VideoService = class extends ServiceModule {
|
|
|
3768
3798
|
async get(videoId, options) {
|
|
3769
3799
|
return super._get(`/${videoId}`, options);
|
|
3770
3800
|
}
|
|
3801
|
+
/**
|
|
3802
|
+
* Register a video from a file already uploaded to scalemule-storage.
|
|
3803
|
+
*
|
|
3804
|
+
* The synchronous handshake for storage-uploaded videos. Verifies the
|
|
3805
|
+
* caller's app owns the storage `file_id` and reads scan status:
|
|
3806
|
+
* - clean → 201, video record created with status='uploading',
|
|
3807
|
+
* transcode worker advances on `scan.file.completed`
|
|
3808
|
+
* - pending → 202, video record created with status='pending_scan',
|
|
3809
|
+
* worker advances when scan completes
|
|
3810
|
+
* - threat → 409 (rejected; row not created)
|
|
3811
|
+
*
|
|
3812
|
+
* Idempotent: calling twice with the same file_id returns the existing
|
|
3813
|
+
* row's data (the underlying INSERT uses ON DUPLICATE KEY UPDATE).
|
|
3814
|
+
*
|
|
3815
|
+
* For storage-backed videos `video_id == file_id` — the response's
|
|
3816
|
+
* `video_id` and `file_id` are identical, and either can be used with
|
|
3817
|
+
* `getStreamUrl()` / `get()`.
|
|
3818
|
+
*
|
|
3819
|
+
* Most callers should use {@link uploadViaStorage} which composes
|
|
3820
|
+
* `storage.uploadPrivate()` + `register()` in a single call.
|
|
3821
|
+
*/
|
|
3822
|
+
async register(request, options) {
|
|
3823
|
+
return this.post(
|
|
3824
|
+
"/register",
|
|
3825
|
+
{
|
|
3826
|
+
file_id: request.fileId,
|
|
3827
|
+
sm_user_id: request.userId
|
|
3828
|
+
},
|
|
3829
|
+
options
|
|
3830
|
+
);
|
|
3831
|
+
}
|
|
3832
|
+
/**
|
|
3833
|
+
* Upload a video to storage (browser → S3 direct, private, no
|
|
3834
|
+
* compression) and register it with the video service so transcoding
|
|
3835
|
+
* + HLS streaming work.
|
|
3836
|
+
*
|
|
3837
|
+
* The canonical chat-attachment / progressive-video upload primitive.
|
|
3838
|
+
* Same private-direct-to-S3 path as `storage.uploadPrivate()`, plus a
|
|
3839
|
+
* follow-up `video.register()` call so HLS playback URLs become live
|
|
3840
|
+
* once the transcoder finishes.
|
|
3841
|
+
*
|
|
3842
|
+
* The returned `hls_url_promise` resolves once the video's status
|
|
3843
|
+
* flips to `ready` (or after a 30s timeout — caller can still serve
|
|
3844
|
+
* `original_view_url` as the fallback). Phase 3 of the realtime-chat
|
|
3845
|
+
* media pipeline ADR replaces the poll with a realtime subscription.
|
|
3846
|
+
*
|
|
3847
|
+
* If `register()` fails after a successful storage upload, the file
|
|
3848
|
+
* is *not* lost: the returned `file_id` is still valid as a generic
|
|
3849
|
+
* storage file. SDK logs a warning and resolves `hls_url_promise`
|
|
3850
|
+
* to `null`.
|
|
3851
|
+
*/
|
|
3852
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
3853
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
3854
|
+
filename: uploadOptions?.filename,
|
|
3855
|
+
metadata: uploadOptions?.metadata,
|
|
3856
|
+
onProgress: uploadOptions?.onProgress,
|
|
3857
|
+
signal: uploadOptions?.signal
|
|
3858
|
+
});
|
|
3859
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
3860
|
+
return { data: null, error: uploadResult.error };
|
|
3861
|
+
}
|
|
3862
|
+
const fileInfo = uploadResult.data;
|
|
3863
|
+
const fileId = fileInfo.id;
|
|
3864
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
3865
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
3866
|
+
if (registerResult.error || !registerResult.data) {
|
|
3867
|
+
console.warn(
|
|
3868
|
+
"[scalemule-sdk] video.register() failed after storage upload; HLS variants unavailable.",
|
|
3869
|
+
registerResult.error
|
|
3870
|
+
);
|
|
3871
|
+
return {
|
|
3872
|
+
data: {
|
|
3873
|
+
file_id: fileId,
|
|
3874
|
+
video_id: fileId,
|
|
3875
|
+
original_view_url: originalViewUrl,
|
|
3876
|
+
hls_url_promise: Promise.resolve(null)
|
|
3877
|
+
},
|
|
3878
|
+
error: null
|
|
3879
|
+
};
|
|
3880
|
+
}
|
|
3881
|
+
const videoId = registerResult.data.video_id;
|
|
3882
|
+
const hlsUrlPromise = this.pollTranscodeComplete(videoId, requestOptions);
|
|
3883
|
+
return {
|
|
3884
|
+
data: {
|
|
3885
|
+
file_id: fileId,
|
|
3886
|
+
video_id: videoId,
|
|
3887
|
+
original_view_url: originalViewUrl,
|
|
3888
|
+
hls_url_promise: hlsUrlPromise
|
|
3889
|
+
},
|
|
3890
|
+
error: null
|
|
3891
|
+
};
|
|
3892
|
+
}
|
|
3893
|
+
/**
|
|
3894
|
+
* Poll {@link get} until the video's status is `ready` or the 30s
|
|
3895
|
+
* timeout fires. Resolves to the HLS master playlist URL on success;
|
|
3896
|
+
* `null` on timeout (caller should fall back to `original_view_url`).
|
|
3897
|
+
*/
|
|
3898
|
+
async pollTranscodeComplete(videoId, requestOptions) {
|
|
3899
|
+
const intervalMs = 1e3;
|
|
3900
|
+
const maxAttempts = 30;
|
|
3901
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
3902
|
+
const result = await this.get(videoId, requestOptions);
|
|
3903
|
+
if (result.data?.status === "ready") {
|
|
3904
|
+
return `${this.client.getBaseUrl()}${this.basePath}/${videoId}/playlist.m3u8`;
|
|
3905
|
+
}
|
|
3906
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
3907
|
+
}
|
|
3908
|
+
return null;
|
|
3909
|
+
}
|
|
3771
3910
|
/**
|
|
3772
3911
|
* Get the HLS master playlist URL for streaming.
|
|
3773
3912
|
* Returns the playlist URL that can be passed to a video player.
|
|
@@ -6768,7 +6907,7 @@ var ScaleMule = class {
|
|
|
6768
6907
|
this.auth = new AuthService(this._client);
|
|
6769
6908
|
this.storage = new StorageService(this._client);
|
|
6770
6909
|
this.realtime = new RealtimeService(this._client);
|
|
6771
|
-
this.video = new VideoService(this._client);
|
|
6910
|
+
this.video = new VideoService(this._client, this.storage);
|
|
6772
6911
|
this.data = new DataService(this._client);
|
|
6773
6912
|
this.chat = new ChatService(this._client);
|
|
6774
6913
|
this.conference = new ConferenceService(this._client);
|