@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 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
- constructor() {
4069
- super(...arguments);
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
- constructor() {
3697
- super(...arguments);
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);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.38",
3
+ "version": "0.0.40",
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",