@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 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
- constructor() {
4035
- super(...arguments);
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
- constructor() {
6046
- super(...arguments);
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
- constructor() {
3663
- super(...arguments);
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
- constructor() {
5674
- super(...arguments);
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);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.37",
3
+ "version": "0.0.39",
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",