@scalemule/sdk 0.0.53 → 0.0.55

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
@@ -1026,10 +1026,53 @@ declare class AuthService extends ServiceModule {
1026
1026
  }): Promise<ApiResponse<AuthSession>>;
1027
1027
  }
1028
1028
 
1029
+ /**
1030
+ * Tri-state file visibility — replaces the overloaded `isPublic`
1031
+ * boolean. Three modes, ordered most-restrictive to most-permissive:
1032
+ *
1033
+ * - `'private'` — signed/private access only. Owner +
1034
+ * app members only.
1035
+ * - `'app_public'` — readable by ANY authenticated end-user
1036
+ * inside the same application. Same
1037
+ * semantics the legacy `isPublic: true`
1038
+ * flag has always carried — NOT
1039
+ * world-readable.
1040
+ * - `'anonymous_visible'` — world-readable on a separate public
1041
+ * CDN with no auth at request time.
1042
+ * Suitable for direct `<img src="…">` use
1043
+ * on a logged-out marketing or blog page.
1044
+ * Must be requested explicitly — never
1045
+ * derived from `isPublic`.
1046
+ *
1047
+ * The storage service backs `anonymous_visible` with a separate S3
1048
+ * bucket fronted by an unsigned CloudFront distribution. When the
1049
+ * environment hasn't provisioned that bucket, `anonymous_visible`
1050
+ * uploads fail loud with HTTP 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
1051
+ * — the SDK never silently demotes them to `app_public`.
1052
+ */
1053
+ type Visibility = 'private' | 'app_public' | 'anonymous_visible';
1029
1054
  interface UploadOptions {
1030
1055
  /** Display filename (sanitized automatically) */
1031
1056
  filename?: string;
1032
- /** Make file publicly accessible */
1057
+ /**
1058
+ * Tri-state visibility (preferred — see {@link Visibility}).
1059
+ * If both `visibility` and `isPublic` are provided, `visibility`
1060
+ * wins. If neither is provided, the storage service defaults to
1061
+ * `app_public` (matching the historical pre-tristate wire
1062
+ * contract). Callers wanting world-visible uploads MUST pass
1063
+ * `'anonymous_visible'` explicitly — `isPublic: true` only ever
1064
+ * means `app_public`.
1065
+ */
1066
+ visibility?: Visibility;
1067
+ /**
1068
+ * Legacy two-state visibility flag.
1069
+ *
1070
+ * - `true` → `app_public` (NOT `anonymous_visible`)
1071
+ * - `false` → `private`
1072
+ *
1073
+ * Prefer the {@link visibility} field for new code. Kept for
1074
+ * back-compat with apps that haven't migrated.
1075
+ */
1033
1076
  isPublic?: boolean;
1034
1077
  /** Custom metadata attached to the file */
1035
1078
  metadata?: Record<string, unknown>;
@@ -1070,6 +1113,18 @@ interface PresignedUploadResponse {
1070
1113
  completion_token: string;
1071
1114
  expires_at: string;
1072
1115
  method: string;
1116
+ /**
1117
+ * Resolved visibility for this upload — may differ from the value
1118
+ * the caller sent (e.g. legacy `is_public: true` → `app_public`).
1119
+ * Returned by storage so the SDK can surface back to callers.
1120
+ */
1121
+ visibility?: Visibility;
1122
+ /**
1123
+ * Stable unsigned CDN URL the file will be served at after upload
1124
+ * completion. Populated only when `visibility === 'anonymous_visible'`.
1125
+ * Safe to embed directly in `<img src>` on a logged-out page.
1126
+ */
1127
+ cdn_url?: string;
1073
1128
  }
1074
1129
  interface UploadCompleteResponse {
1075
1130
  file_id: string;
@@ -1079,6 +1134,10 @@ interface UploadCompleteResponse {
1079
1134
  url: string;
1080
1135
  already_completed: boolean;
1081
1136
  scan_queued: boolean;
1137
+ /** Resolved visibility (see {@link PresignedUploadResponse.visibility}). */
1138
+ visibility?: Visibility;
1139
+ /** Unsigned CDN URL — populated only for `anonymous_visible` files. */
1140
+ cdn_url?: string;
1082
1141
  }
1083
1142
  interface UploadFailureReport {
1084
1143
  fileId: string;
@@ -1119,6 +1178,10 @@ interface MultipartCompleteResponse {
1119
1178
  content_type: string;
1120
1179
  url: string;
1121
1180
  scan_queued: boolean;
1181
+ /** Resolved visibility — present on multipart_complete responses. */
1182
+ visibility?: Visibility;
1183
+ /** Unsigned CDN URL — populated only for `anonymous_visible` files. */
1184
+ cdn_url?: string;
1122
1185
  }
1123
1186
  interface FileInfo {
1124
1187
  id: string;
@@ -1126,6 +1189,29 @@ interface FileInfo {
1126
1189
  content_type: string;
1127
1190
  size_bytes: number;
1128
1191
  is_public?: boolean;
1192
+ /**
1193
+ * Tri-state visibility from the storage service. Preferred over
1194
+ * `is_public` — `is_public: true` covers both `app_public` and
1195
+ * `anonymous_visible`, which have very different delivery
1196
+ * contracts.
1197
+ */
1198
+ visibility?: Visibility;
1199
+ /**
1200
+ * Bucket the file's bytes live in. For `anonymous_visible` files
1201
+ * this is the storage anonymous bucket; otherwise the standard
1202
+ * `scalemule-storage*` bucket. Empty string when older storage
1203
+ * instances don't return it — callers should treat that as
1204
+ * "primary bucket".
1205
+ */
1206
+ bucket_name?: string;
1207
+ /**
1208
+ * Stable unsigned public-CDN URL — populated only when
1209
+ * `visibility === 'anonymous_visible'`. Drop directly into
1210
+ * `<img src>` on logged-out pages. For private/app_public files
1211
+ * use {@link StorageService.getViewUrl} or
1212
+ * {@link StorageService.getDownloadUrl} instead.
1213
+ */
1214
+ cdn_url?: string;
1129
1215
  url?: string;
1130
1216
  scan_status?: string;
1131
1217
  scanned_at?: string;
@@ -1189,6 +1275,13 @@ interface FileStatus {
1189
1275
  * S3-presigned otherwise). Absent when scan is `threat` /
1190
1276
  * `quarantined` / `error` — consumers render a blocked
1191
1277
  * placeholder when this is null + scan is non-clean.
1278
+ *
1279
+ * For `visibility = anonymous_visible` files, this field is
1280
+ * ALSO null until scan has flipped to `clean` — the
1281
+ * release-async carve-out only applies to auth-gated tiers,
1282
+ * since for anon files any URL is world-readable. Use
1283
+ * {@link cdn_url} (which has the same gate but is typed
1284
+ * specifically for the public-CDN case) to branch reliably.
1192
1285
  */
1193
1286
  original?: string;
1194
1287
  /** Gateway path for the photo transform — present only when the
@@ -1197,6 +1290,27 @@ interface FileStatus {
1197
1290
  /** Gateway path for the HLS master playlist — present only when the
1198
1291
  * transcode worker reports `transcode.status === 'done'` (video only). */
1199
1292
  hls?: string;
1293
+ /**
1294
+ * **Typed** unsigned public CDN URL — populated only when
1295
+ * `visibility === 'anonymous_visible'` AND scan has flipped to
1296
+ * `clean` (or admin-released). Lets polling consumers
1297
+ * (`useFileStatus()`) surface the public URL the moment it
1298
+ * becomes available without a separate `getInfo()` /
1299
+ * `list()` call. Mirrors the contract on
1300
+ * {@link FileInfo.cdn_url} and the upload-complete response.
1301
+ *
1302
+ * Polling pattern:
1303
+ * ```ts
1304
+ * while (true) {
1305
+ * const r = await sm.storage.getFileStatus(fileId);
1306
+ * if (r.data.urls.cdn_url) break; // safe to publish
1307
+ * if (['threat','quarantined','error'].includes(r.data.scan.status))
1308
+ * break; // failed terminal
1309
+ * await sleep(1000);
1310
+ * }
1311
+ * ```
1312
+ */
1313
+ cdn_url?: string;
1200
1314
  };
1201
1315
  }
1202
1316
  declare class StorageService extends ServiceModule {
@@ -1228,6 +1342,37 @@ declare class StorageService extends ServiceModule {
1228
1342
  * docs/MEDIA-UPLOADS.md for the full pattern.
1229
1343
  */
1230
1344
  uploadPrivate(file: File | Blob, options?: Omit<UploadOptions, 'isPublic' | 'skipCompression'>): Promise<ApiResponse<FileInfo>>;
1345
+ /**
1346
+ * Upload a file as world-readable on the anonymous public CDN.
1347
+ *
1348
+ * Same browser→S3 pipeline as {@link upload}, but pins
1349
+ * `visibility: 'anonymous_visible'` — caller cannot opt out.
1350
+ *
1351
+ * Use this for media meant to render on logged-out marketing
1352
+ * pages, blog posts, embed snippets — anywhere a customer needs
1353
+ * to drop a URL into `<img src>` without an authenticated
1354
+ * session. For everything else (chat attachments, private
1355
+ * uploads, app-internal galleries) prefer {@link upload} or
1356
+ * {@link uploadPrivate}.
1357
+ *
1358
+ * **`cdn_url` may be `null` on the immediate response.** Storage
1359
+ * intentionally withholds the public CDN URL until the AV scan
1360
+ * has flipped to `clean` — exposing the URL pre-scan would let a
1361
+ * customer embed the bytes in a logged-out page before the
1362
+ * platform has verified them. The upload itself succeeds
1363
+ * regardless; consumers should check `result.data.cdn_url` and:
1364
+ * - if non-null → it's safe to publish
1365
+ * - if null → poll {@link getFileStatus} on a small backoff
1366
+ * until `urls.cdn_url` populates (or `scan.status` flips to
1367
+ * `threat` / `quarantined` / `error` — terminal failure)
1368
+ *
1369
+ * Requires the operator to have provisioned the anonymous
1370
+ * delivery bucket + CDN. When they haven't, the storage service
1371
+ * returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED` (an error
1372
+ * propagated through this helper) — it never silently demotes
1373
+ * to `app_public`.
1374
+ */
1375
+ uploadAnonymous(file: File | Blob, options?: Omit<UploadOptions, 'visibility' | 'isPublic'>): Promise<ApiResponse<FileInfo>>;
1231
1376
  private uploadDirect;
1232
1377
  private uploadMultipart;
1233
1378
  private abortMultipart;
@@ -1239,6 +1384,9 @@ declare class StorageService extends ServiceModule {
1239
1384
  * Flow: server calls getUploadUrl() → returns URL to client → client PUTs to S3 → server calls completeUpload()
1240
1385
  */
1241
1386
  getUploadUrl(filename: string, contentType: string, options?: {
1387
+ /** Tri-state visibility (preferred). See {@link Visibility}. */
1388
+ visibility?: Visibility;
1389
+ /** Legacy boolean. `true` → app_public, `false` → private. */
1242
1390
  isPublic?: boolean;
1243
1391
  expiresIn?: number;
1244
1392
  sizeBytes?: number;
@@ -1257,11 +1405,21 @@ declare class StorageService extends ServiceModule {
1257
1405
  * Best used by split-upload clients that call getUploadUrl() manually.
1258
1406
  */
1259
1407
  reportUploadFailure(params: UploadFailureReport, requestOptions?: RequestOptions): Promise<ApiResponse<UploadFailureReportResponse>>;
1260
- /** Start a multipart upload session. */
1408
+ /**
1409
+ * Start a multipart upload session.
1410
+ *
1411
+ * Accepts both the typed `visibility` field (preferred) and the
1412
+ * legacy `is_public` boolean for back-compat. If both are sent the
1413
+ * storage service uses `visibility`. `'anonymous_visible'` requires
1414
+ * the operator to have provisioned the anonymous bucket — the
1415
+ * service returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
1416
+ * otherwise (the SDK never silently demotes).
1417
+ */
1261
1418
  startMultipartUpload(params: {
1262
1419
  filename: string;
1263
1420
  content_type: string;
1264
1421
  size_bytes: number;
1422
+ visibility?: Visibility;
1265
1423
  is_public?: boolean;
1266
1424
  metadata?: Record<string, unknown>;
1267
1425
  chunk_size?: number;
@@ -1364,12 +1522,24 @@ declare class StorageService extends ServiceModule {
1364
1522
  url?: string;
1365
1523
  }>>;
1366
1524
  /**
1367
- * Update a file's visibility (public/private).
1368
- * Only the file owner can toggle this. Changes URL TTL — does not move the S3 object.
1369
- * Public files get 7-day signed URLs; private files get 1-hour signed URLs.
1525
+ * Update a file's visibility.
1526
+ *
1527
+ * Accepts either:
1528
+ * - a tri-state {@link Visibility} string (preferred), or
1529
+ * - a legacy boolean (`true` → `app_public`, `false` → `private`).
1530
+ *
1531
+ * Only the file owner / app member can toggle this. Same-bucket
1532
+ * transitions (`private` ↔ `app_public`) succeed and the service
1533
+ * keeps the legacy `is_public` column in sync via a DB trigger.
1534
+ * Cross-bucket transitions (any flip into or out of
1535
+ * `'anonymous_visible'`) currently return 409
1536
+ * `VISIBILITY_TRANSITION_UNSUPPORTED` — the bytes would need to
1537
+ * move between S3 buckets and that orchestration is not yet
1538
+ * shipped. Re-upload the file with the desired visibility instead.
1370
1539
  */
1371
- updateVisibility(fileId: string, isPublic: boolean, options?: RequestOptions): Promise<ApiResponse<{
1540
+ updateVisibility(fileId: string, visibility: Visibility | boolean, options?: RequestOptions): Promise<ApiResponse<{
1372
1541
  file_id: string;
1542
+ visibility: Visibility;
1373
1543
  is_public: boolean;
1374
1544
  }>>;
1375
1545
  /** @deprecated Use upload() instead */
@@ -4583,6 +4753,32 @@ declare class PhotoService extends ServiceModule {
4583
4753
  * Transformed images are cached server-side on first request.
4584
4754
  */
4585
4755
  getTransformUrl(photoId: string, options?: TransformOptions): string;
4756
+ /**
4757
+ * Build an absolute URL for the **public** transform endpoint —
4758
+ * the unauthenticated path that serves transformed bytes for
4759
+ * `<img src>` use on logged-out marketing pages, blogs, embeds.
4760
+ *
4761
+ * The photo service refuses any photo that isn't:
4762
+ * - `visibility = 'anonymous_visible'` (the customer explicitly
4763
+ * opted into world-readable for this file at upload time)
4764
+ * - `scan_status = 'clean'` (no exception for pending/scanning)
4765
+ *
4766
+ * Anything else returns 404 — the endpoint refuses to disambiguate
4767
+ * "not found" from "not anonymous" so it can't be probed to
4768
+ * discover existence or visibility of private photos.
4769
+ *
4770
+ * Pair with {@link getTransformUrl} for the authenticated case:
4771
+ * customer apps that already have a session should keep using the
4772
+ * authed transform URL (which also handles `anonymous_visible`
4773
+ * photos transparently) — this URL is for cross-origin embedding.
4774
+ *
4775
+ * @example
4776
+ * ```tsx
4777
+ * // photo was uploaded with visibility: 'anonymous_visible'
4778
+ * <img src={sm.photo.getPublicTransformUrl(photoId, { width: 800 })} />
4779
+ * ```
4780
+ */
4781
+ getPublicTransformUrl(photoId: string, options?: TransformOptions): string;
4586
4782
  /**
4587
4783
  * Get a transform URL optimized for the given display area.
4588
4784
  *
package/dist/index.d.ts CHANGED
@@ -1026,10 +1026,53 @@ declare class AuthService extends ServiceModule {
1026
1026
  }): Promise<ApiResponse<AuthSession>>;
1027
1027
  }
1028
1028
 
1029
+ /**
1030
+ * Tri-state file visibility — replaces the overloaded `isPublic`
1031
+ * boolean. Three modes, ordered most-restrictive to most-permissive:
1032
+ *
1033
+ * - `'private'` — signed/private access only. Owner +
1034
+ * app members only.
1035
+ * - `'app_public'` — readable by ANY authenticated end-user
1036
+ * inside the same application. Same
1037
+ * semantics the legacy `isPublic: true`
1038
+ * flag has always carried — NOT
1039
+ * world-readable.
1040
+ * - `'anonymous_visible'` — world-readable on a separate public
1041
+ * CDN with no auth at request time.
1042
+ * Suitable for direct `<img src="…">` use
1043
+ * on a logged-out marketing or blog page.
1044
+ * Must be requested explicitly — never
1045
+ * derived from `isPublic`.
1046
+ *
1047
+ * The storage service backs `anonymous_visible` with a separate S3
1048
+ * bucket fronted by an unsigned CloudFront distribution. When the
1049
+ * environment hasn't provisioned that bucket, `anonymous_visible`
1050
+ * uploads fail loud with HTTP 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
1051
+ * — the SDK never silently demotes them to `app_public`.
1052
+ */
1053
+ type Visibility = 'private' | 'app_public' | 'anonymous_visible';
1029
1054
  interface UploadOptions {
1030
1055
  /** Display filename (sanitized automatically) */
1031
1056
  filename?: string;
1032
- /** Make file publicly accessible */
1057
+ /**
1058
+ * Tri-state visibility (preferred — see {@link Visibility}).
1059
+ * If both `visibility` and `isPublic` are provided, `visibility`
1060
+ * wins. If neither is provided, the storage service defaults to
1061
+ * `app_public` (matching the historical pre-tristate wire
1062
+ * contract). Callers wanting world-visible uploads MUST pass
1063
+ * `'anonymous_visible'` explicitly — `isPublic: true` only ever
1064
+ * means `app_public`.
1065
+ */
1066
+ visibility?: Visibility;
1067
+ /**
1068
+ * Legacy two-state visibility flag.
1069
+ *
1070
+ * - `true` → `app_public` (NOT `anonymous_visible`)
1071
+ * - `false` → `private`
1072
+ *
1073
+ * Prefer the {@link visibility} field for new code. Kept for
1074
+ * back-compat with apps that haven't migrated.
1075
+ */
1033
1076
  isPublic?: boolean;
1034
1077
  /** Custom metadata attached to the file */
1035
1078
  metadata?: Record<string, unknown>;
@@ -1070,6 +1113,18 @@ interface PresignedUploadResponse {
1070
1113
  completion_token: string;
1071
1114
  expires_at: string;
1072
1115
  method: string;
1116
+ /**
1117
+ * Resolved visibility for this upload — may differ from the value
1118
+ * the caller sent (e.g. legacy `is_public: true` → `app_public`).
1119
+ * Returned by storage so the SDK can surface back to callers.
1120
+ */
1121
+ visibility?: Visibility;
1122
+ /**
1123
+ * Stable unsigned CDN URL the file will be served at after upload
1124
+ * completion. Populated only when `visibility === 'anonymous_visible'`.
1125
+ * Safe to embed directly in `<img src>` on a logged-out page.
1126
+ */
1127
+ cdn_url?: string;
1073
1128
  }
1074
1129
  interface UploadCompleteResponse {
1075
1130
  file_id: string;
@@ -1079,6 +1134,10 @@ interface UploadCompleteResponse {
1079
1134
  url: string;
1080
1135
  already_completed: boolean;
1081
1136
  scan_queued: boolean;
1137
+ /** Resolved visibility (see {@link PresignedUploadResponse.visibility}). */
1138
+ visibility?: Visibility;
1139
+ /** Unsigned CDN URL — populated only for `anonymous_visible` files. */
1140
+ cdn_url?: string;
1082
1141
  }
1083
1142
  interface UploadFailureReport {
1084
1143
  fileId: string;
@@ -1119,6 +1178,10 @@ interface MultipartCompleteResponse {
1119
1178
  content_type: string;
1120
1179
  url: string;
1121
1180
  scan_queued: boolean;
1181
+ /** Resolved visibility — present on multipart_complete responses. */
1182
+ visibility?: Visibility;
1183
+ /** Unsigned CDN URL — populated only for `anonymous_visible` files. */
1184
+ cdn_url?: string;
1122
1185
  }
1123
1186
  interface FileInfo {
1124
1187
  id: string;
@@ -1126,6 +1189,29 @@ interface FileInfo {
1126
1189
  content_type: string;
1127
1190
  size_bytes: number;
1128
1191
  is_public?: boolean;
1192
+ /**
1193
+ * Tri-state visibility from the storage service. Preferred over
1194
+ * `is_public` — `is_public: true` covers both `app_public` and
1195
+ * `anonymous_visible`, which have very different delivery
1196
+ * contracts.
1197
+ */
1198
+ visibility?: Visibility;
1199
+ /**
1200
+ * Bucket the file's bytes live in. For `anonymous_visible` files
1201
+ * this is the storage anonymous bucket; otherwise the standard
1202
+ * `scalemule-storage*` bucket. Empty string when older storage
1203
+ * instances don't return it — callers should treat that as
1204
+ * "primary bucket".
1205
+ */
1206
+ bucket_name?: string;
1207
+ /**
1208
+ * Stable unsigned public-CDN URL — populated only when
1209
+ * `visibility === 'anonymous_visible'`. Drop directly into
1210
+ * `<img src>` on logged-out pages. For private/app_public files
1211
+ * use {@link StorageService.getViewUrl} or
1212
+ * {@link StorageService.getDownloadUrl} instead.
1213
+ */
1214
+ cdn_url?: string;
1129
1215
  url?: string;
1130
1216
  scan_status?: string;
1131
1217
  scanned_at?: string;
@@ -1189,6 +1275,13 @@ interface FileStatus {
1189
1275
  * S3-presigned otherwise). Absent when scan is `threat` /
1190
1276
  * `quarantined` / `error` — consumers render a blocked
1191
1277
  * placeholder when this is null + scan is non-clean.
1278
+ *
1279
+ * For `visibility = anonymous_visible` files, this field is
1280
+ * ALSO null until scan has flipped to `clean` — the
1281
+ * release-async carve-out only applies to auth-gated tiers,
1282
+ * since for anon files any URL is world-readable. Use
1283
+ * {@link cdn_url} (which has the same gate but is typed
1284
+ * specifically for the public-CDN case) to branch reliably.
1192
1285
  */
1193
1286
  original?: string;
1194
1287
  /** Gateway path for the photo transform — present only when the
@@ -1197,6 +1290,27 @@ interface FileStatus {
1197
1290
  /** Gateway path for the HLS master playlist — present only when the
1198
1291
  * transcode worker reports `transcode.status === 'done'` (video only). */
1199
1292
  hls?: string;
1293
+ /**
1294
+ * **Typed** unsigned public CDN URL — populated only when
1295
+ * `visibility === 'anonymous_visible'` AND scan has flipped to
1296
+ * `clean` (or admin-released). Lets polling consumers
1297
+ * (`useFileStatus()`) surface the public URL the moment it
1298
+ * becomes available without a separate `getInfo()` /
1299
+ * `list()` call. Mirrors the contract on
1300
+ * {@link FileInfo.cdn_url} and the upload-complete response.
1301
+ *
1302
+ * Polling pattern:
1303
+ * ```ts
1304
+ * while (true) {
1305
+ * const r = await sm.storage.getFileStatus(fileId);
1306
+ * if (r.data.urls.cdn_url) break; // safe to publish
1307
+ * if (['threat','quarantined','error'].includes(r.data.scan.status))
1308
+ * break; // failed terminal
1309
+ * await sleep(1000);
1310
+ * }
1311
+ * ```
1312
+ */
1313
+ cdn_url?: string;
1200
1314
  };
1201
1315
  }
1202
1316
  declare class StorageService extends ServiceModule {
@@ -1228,6 +1342,37 @@ declare class StorageService extends ServiceModule {
1228
1342
  * docs/MEDIA-UPLOADS.md for the full pattern.
1229
1343
  */
1230
1344
  uploadPrivate(file: File | Blob, options?: Omit<UploadOptions, 'isPublic' | 'skipCompression'>): Promise<ApiResponse<FileInfo>>;
1345
+ /**
1346
+ * Upload a file as world-readable on the anonymous public CDN.
1347
+ *
1348
+ * Same browser→S3 pipeline as {@link upload}, but pins
1349
+ * `visibility: 'anonymous_visible'` — caller cannot opt out.
1350
+ *
1351
+ * Use this for media meant to render on logged-out marketing
1352
+ * pages, blog posts, embed snippets — anywhere a customer needs
1353
+ * to drop a URL into `<img src>` without an authenticated
1354
+ * session. For everything else (chat attachments, private
1355
+ * uploads, app-internal galleries) prefer {@link upload} or
1356
+ * {@link uploadPrivate}.
1357
+ *
1358
+ * **`cdn_url` may be `null` on the immediate response.** Storage
1359
+ * intentionally withholds the public CDN URL until the AV scan
1360
+ * has flipped to `clean` — exposing the URL pre-scan would let a
1361
+ * customer embed the bytes in a logged-out page before the
1362
+ * platform has verified them. The upload itself succeeds
1363
+ * regardless; consumers should check `result.data.cdn_url` and:
1364
+ * - if non-null → it's safe to publish
1365
+ * - if null → poll {@link getFileStatus} on a small backoff
1366
+ * until `urls.cdn_url` populates (or `scan.status` flips to
1367
+ * `threat` / `quarantined` / `error` — terminal failure)
1368
+ *
1369
+ * Requires the operator to have provisioned the anonymous
1370
+ * delivery bucket + CDN. When they haven't, the storage service
1371
+ * returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED` (an error
1372
+ * propagated through this helper) — it never silently demotes
1373
+ * to `app_public`.
1374
+ */
1375
+ uploadAnonymous(file: File | Blob, options?: Omit<UploadOptions, 'visibility' | 'isPublic'>): Promise<ApiResponse<FileInfo>>;
1231
1376
  private uploadDirect;
1232
1377
  private uploadMultipart;
1233
1378
  private abortMultipart;
@@ -1239,6 +1384,9 @@ declare class StorageService extends ServiceModule {
1239
1384
  * Flow: server calls getUploadUrl() → returns URL to client → client PUTs to S3 → server calls completeUpload()
1240
1385
  */
1241
1386
  getUploadUrl(filename: string, contentType: string, options?: {
1387
+ /** Tri-state visibility (preferred). See {@link Visibility}. */
1388
+ visibility?: Visibility;
1389
+ /** Legacy boolean. `true` → app_public, `false` → private. */
1242
1390
  isPublic?: boolean;
1243
1391
  expiresIn?: number;
1244
1392
  sizeBytes?: number;
@@ -1257,11 +1405,21 @@ declare class StorageService extends ServiceModule {
1257
1405
  * Best used by split-upload clients that call getUploadUrl() manually.
1258
1406
  */
1259
1407
  reportUploadFailure(params: UploadFailureReport, requestOptions?: RequestOptions): Promise<ApiResponse<UploadFailureReportResponse>>;
1260
- /** Start a multipart upload session. */
1408
+ /**
1409
+ * Start a multipart upload session.
1410
+ *
1411
+ * Accepts both the typed `visibility` field (preferred) and the
1412
+ * legacy `is_public` boolean for back-compat. If both are sent the
1413
+ * storage service uses `visibility`. `'anonymous_visible'` requires
1414
+ * the operator to have provisioned the anonymous bucket — the
1415
+ * service returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
1416
+ * otherwise (the SDK never silently demotes).
1417
+ */
1261
1418
  startMultipartUpload(params: {
1262
1419
  filename: string;
1263
1420
  content_type: string;
1264
1421
  size_bytes: number;
1422
+ visibility?: Visibility;
1265
1423
  is_public?: boolean;
1266
1424
  metadata?: Record<string, unknown>;
1267
1425
  chunk_size?: number;
@@ -1364,12 +1522,24 @@ declare class StorageService extends ServiceModule {
1364
1522
  url?: string;
1365
1523
  }>>;
1366
1524
  /**
1367
- * Update a file's visibility (public/private).
1368
- * Only the file owner can toggle this. Changes URL TTL — does not move the S3 object.
1369
- * Public files get 7-day signed URLs; private files get 1-hour signed URLs.
1525
+ * Update a file's visibility.
1526
+ *
1527
+ * Accepts either:
1528
+ * - a tri-state {@link Visibility} string (preferred), or
1529
+ * - a legacy boolean (`true` → `app_public`, `false` → `private`).
1530
+ *
1531
+ * Only the file owner / app member can toggle this. Same-bucket
1532
+ * transitions (`private` ↔ `app_public`) succeed and the service
1533
+ * keeps the legacy `is_public` column in sync via a DB trigger.
1534
+ * Cross-bucket transitions (any flip into or out of
1535
+ * `'anonymous_visible'`) currently return 409
1536
+ * `VISIBILITY_TRANSITION_UNSUPPORTED` — the bytes would need to
1537
+ * move between S3 buckets and that orchestration is not yet
1538
+ * shipped. Re-upload the file with the desired visibility instead.
1370
1539
  */
1371
- updateVisibility(fileId: string, isPublic: boolean, options?: RequestOptions): Promise<ApiResponse<{
1540
+ updateVisibility(fileId: string, visibility: Visibility | boolean, options?: RequestOptions): Promise<ApiResponse<{
1372
1541
  file_id: string;
1542
+ visibility: Visibility;
1373
1543
  is_public: boolean;
1374
1544
  }>>;
1375
1545
  /** @deprecated Use upload() instead */
@@ -4583,6 +4753,32 @@ declare class PhotoService extends ServiceModule {
4583
4753
  * Transformed images are cached server-side on first request.
4584
4754
  */
4585
4755
  getTransformUrl(photoId: string, options?: TransformOptions): string;
4756
+ /**
4757
+ * Build an absolute URL for the **public** transform endpoint —
4758
+ * the unauthenticated path that serves transformed bytes for
4759
+ * `<img src>` use on logged-out marketing pages, blogs, embeds.
4760
+ *
4761
+ * The photo service refuses any photo that isn't:
4762
+ * - `visibility = 'anonymous_visible'` (the customer explicitly
4763
+ * opted into world-readable for this file at upload time)
4764
+ * - `scan_status = 'clean'` (no exception for pending/scanning)
4765
+ *
4766
+ * Anything else returns 404 — the endpoint refuses to disambiguate
4767
+ * "not found" from "not anonymous" so it can't be probed to
4768
+ * discover existence or visibility of private photos.
4769
+ *
4770
+ * Pair with {@link getTransformUrl} for the authenticated case:
4771
+ * customer apps that already have a session should keep using the
4772
+ * authed transform URL (which also handles `anonymous_visible`
4773
+ * photos transparently) — this URL is for cross-origin embedding.
4774
+ *
4775
+ * @example
4776
+ * ```tsx
4777
+ * // photo was uploaded with visibility: 'anonymous_visible'
4778
+ * <img src={sm.photo.getPublicTransformUrl(photoId, { width: 800 })} />
4779
+ * ```
4780
+ */
4781
+ getPublicTransformUrl(photoId: string, options?: TransformOptions): string;
4586
4782
  /**
4587
4783
  * Get a transform URL optimized for the given display area.
4588
4784
  *
package/dist/index.js CHANGED
@@ -2331,6 +2331,24 @@ var DEFAULT_STALL_TIMEOUT_MS = 45e3;
2331
2331
  var SLOW_NETWORK_STALL_TIMEOUT_MS = 9e4;
2332
2332
  var MULTIPART_THRESHOLD = 8 * 1024 * 1024;
2333
2333
  var MULTIPART_THRESHOLD_SLOW = 4 * 1024 * 1024;
2334
+ function buildVisibilityWire(options) {
2335
+ if (!options) return {};
2336
+ if (options.visibility) {
2337
+ return {
2338
+ visibility: options.visibility,
2339
+ // Legacy field for old storage instances that haven't deployed
2340
+ // the tristate handler yet — omit `is_public` for the
2341
+ // `anonymous_visible` case so an old server that doesn't know
2342
+ // the new value at least falls through to its own default
2343
+ // rather than mis-treating it as `app_public`.
2344
+ ...options.visibility === "private" ? { is_public: false } : options.visibility === "app_public" ? { is_public: true } : {}
2345
+ };
2346
+ }
2347
+ if (typeof options.isPublic === "boolean") {
2348
+ return { is_public: options.isPublic };
2349
+ }
2350
+ return {};
2351
+ }
2334
2352
  var StorageService = class extends ServiceModule {
2335
2353
  constructor() {
2336
2354
  super(...arguments);
@@ -2412,6 +2430,42 @@ var StorageService = class extends ServiceModule {
2412
2430
  }
2413
2431
  return result;
2414
2432
  }
2433
+ /**
2434
+ * Upload a file as world-readable on the anonymous public CDN.
2435
+ *
2436
+ * Same browser→S3 pipeline as {@link upload}, but pins
2437
+ * `visibility: 'anonymous_visible'` — caller cannot opt out.
2438
+ *
2439
+ * Use this for media meant to render on logged-out marketing
2440
+ * pages, blog posts, embed snippets — anywhere a customer needs
2441
+ * to drop a URL into `<img src>` without an authenticated
2442
+ * session. For everything else (chat attachments, private
2443
+ * uploads, app-internal galleries) prefer {@link upload} or
2444
+ * {@link uploadPrivate}.
2445
+ *
2446
+ * **`cdn_url` may be `null` on the immediate response.** Storage
2447
+ * intentionally withholds the public CDN URL until the AV scan
2448
+ * has flipped to `clean` — exposing the URL pre-scan would let a
2449
+ * customer embed the bytes in a logged-out page before the
2450
+ * platform has verified them. The upload itself succeeds
2451
+ * regardless; consumers should check `result.data.cdn_url` and:
2452
+ * - if non-null → it's safe to publish
2453
+ * - if null → poll {@link getFileStatus} on a small backoff
2454
+ * until `urls.cdn_url` populates (or `scan.status` flips to
2455
+ * `threat` / `quarantined` / `error` — terminal failure)
2456
+ *
2457
+ * Requires the operator to have provisioned the anonymous
2458
+ * delivery bucket + CDN. When they haven't, the storage service
2459
+ * returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED` (an error
2460
+ * propagated through this helper) — it never silently demotes
2461
+ * to `app_public`.
2462
+ */
2463
+ async uploadAnonymous(file, options) {
2464
+ return this.upload(file, {
2465
+ ...options,
2466
+ visibility: "anonymous_visible"
2467
+ });
2468
+ }
2415
2469
  // --------------------------------------------------------------------------
2416
2470
  // Direct Upload (3-step with retry + stall)
2417
2471
  // --------------------------------------------------------------------------
@@ -2425,7 +2479,7 @@ var StorageService = class extends ServiceModule {
2425
2479
  filename,
2426
2480
  content_type: file.type || "application/octet-stream",
2427
2481
  size_bytes: file.size,
2428
- is_public: options?.isPublic ?? true,
2482
+ ...buildVisibilityWire(options),
2429
2483
  metadata: options?.metadata
2430
2484
  },
2431
2485
  requestOpts
@@ -2516,6 +2570,13 @@ var StorageService = class extends ServiceModule {
2516
2570
  content_type: d.content_type,
2517
2571
  size_bytes: d.size_bytes,
2518
2572
  url: d.url,
2573
+ // Surface visibility + cdn_url all the way out so callers
2574
+ // can branch on visibility without a follow-up getInfo()
2575
+ // round-trip. Anonymous-visible callers especially need
2576
+ // `cdn_url` here to render the image immediately.
2577
+ visibility: d.visibility,
2578
+ cdn_url: d.cdn_url,
2579
+ is_public: d.visibility ? d.visibility !== "private" : void 0,
2519
2580
  created_at: (/* @__PURE__ */ new Date()).toISOString()
2520
2581
  },
2521
2582
  error: null
@@ -2597,7 +2658,7 @@ var StorageService = class extends ServiceModule {
2597
2658
  filename,
2598
2659
  content_type: file.type || "application/octet-stream",
2599
2660
  size_bytes: file.size,
2600
- is_public: options?.isPublic ?? true,
2661
+ ...buildVisibilityWire(options),
2601
2662
  metadata: options?.metadata,
2602
2663
  chunk_size: options?.chunkSize,
2603
2664
  ...clientUploadKey ? { client_upload_key: clientUploadKey } : {}
@@ -2875,6 +2936,9 @@ var StorageService = class extends ServiceModule {
2875
2936
  content_type: d.content_type,
2876
2937
  size_bytes: d.size_bytes,
2877
2938
  url: d.url,
2939
+ visibility: d.visibility,
2940
+ cdn_url: d.cdn_url,
2941
+ is_public: d.visibility ? d.visibility !== "private" : void 0,
2878
2942
  created_at: (/* @__PURE__ */ new Date()).toISOString()
2879
2943
  },
2880
2944
  error: null
@@ -2912,7 +2976,7 @@ var StorageService = class extends ServiceModule {
2912
2976
  {
2913
2977
  filename,
2914
2978
  content_type: contentType,
2915
- is_public: options?.isPublic ?? true,
2979
+ ...buildVisibilityWire(options),
2916
2980
  expires_in: options?.expiresIn ?? 3600,
2917
2981
  size_bytes: options?.sizeBytes,
2918
2982
  metadata: options?.metadata
@@ -2959,7 +3023,16 @@ var StorageService = class extends ServiceModule {
2959
3023
  // --------------------------------------------------------------------------
2960
3024
  // Multipart Public API (for advanced/server-side usage)
2961
3025
  // --------------------------------------------------------------------------
2962
- /** Start a multipart upload session. */
3026
+ /**
3027
+ * Start a multipart upload session.
3028
+ *
3029
+ * Accepts both the typed `visibility` field (preferred) and the
3030
+ * legacy `is_public` boolean for back-compat. If both are sent the
3031
+ * storage service uses `visibility`. `'anonymous_visible'` requires
3032
+ * the operator to have provisioned the anonymous bucket — the
3033
+ * service returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
3034
+ * otherwise (the SDK never silently demotes).
3035
+ */
2963
3036
  async startMultipartUpload(params, requestOptions) {
2964
3037
  return this.post("/signed-url/multipart/start", params, requestOptions);
2965
3038
  }
@@ -3090,14 +3163,26 @@ var StorageService = class extends ServiceModule {
3090
3163
  return this._get(`/files/${fileId}/view-status`, options);
3091
3164
  }
3092
3165
  /**
3093
- * Update a file's visibility (public/private).
3094
- * Only the file owner can toggle this. Changes URL TTL — does not move the S3 object.
3095
- * Public files get 7-day signed URLs; private files get 1-hour signed URLs.
3166
+ * Update a file's visibility.
3167
+ *
3168
+ * Accepts either:
3169
+ * - a tri-state {@link Visibility} string (preferred), or
3170
+ * - a legacy boolean (`true` → `app_public`, `false` → `private`).
3171
+ *
3172
+ * Only the file owner / app member can toggle this. Same-bucket
3173
+ * transitions (`private` ↔ `app_public`) succeed and the service
3174
+ * keeps the legacy `is_public` column in sync via a DB trigger.
3175
+ * Cross-bucket transitions (any flip into or out of
3176
+ * `'anonymous_visible'`) currently return 409
3177
+ * `VISIBILITY_TRANSITION_UNSUPPORTED` — the bytes would need to
3178
+ * move between S3 buckets and that orchestration is not yet
3179
+ * shipped. Re-upload the file with the desired visibility instead.
3096
3180
  */
3097
- async updateVisibility(fileId, isPublic, options) {
3181
+ async updateVisibility(fileId, visibility, options) {
3182
+ const body = typeof visibility === "boolean" ? { is_public: visibility } : { visibility };
3098
3183
  return this.patch(
3099
3184
  `/files/${fileId}/visibility`,
3100
- { is_public: isPublic },
3185
+ body,
3101
3186
  options
3102
3187
  );
3103
3188
  }
@@ -6496,6 +6581,41 @@ var PhotoService = class extends ServiceModule {
6496
6581
  const qs = params.toString();
6497
6582
  return `${this.client.getBaseUrl()}${this.basePath}/${photoId}/transform${qs ? `?${qs}` : ""}`;
6498
6583
  }
6584
+ /**
6585
+ * Build an absolute URL for the **public** transform endpoint —
6586
+ * the unauthenticated path that serves transformed bytes for
6587
+ * `<img src>` use on logged-out marketing pages, blogs, embeds.
6588
+ *
6589
+ * The photo service refuses any photo that isn't:
6590
+ * - `visibility = 'anonymous_visible'` (the customer explicitly
6591
+ * opted into world-readable for this file at upload time)
6592
+ * - `scan_status = 'clean'` (no exception for pending/scanning)
6593
+ *
6594
+ * Anything else returns 404 — the endpoint refuses to disambiguate
6595
+ * "not found" from "not anonymous" so it can't be probed to
6596
+ * discover existence or visibility of private photos.
6597
+ *
6598
+ * Pair with {@link getTransformUrl} for the authenticated case:
6599
+ * customer apps that already have a session should keep using the
6600
+ * authed transform URL (which also handles `anonymous_visible`
6601
+ * photos transparently) — this URL is for cross-origin embedding.
6602
+ *
6603
+ * @example
6604
+ * ```tsx
6605
+ * // photo was uploaded with visibility: 'anonymous_visible'
6606
+ * <img src={sm.photo.getPublicTransformUrl(photoId, { width: 800 })} />
6607
+ * ```
6608
+ */
6609
+ getPublicTransformUrl(photoId, options) {
6610
+ const params = new URLSearchParams();
6611
+ if (options?.width) params.set("width", String(options.width));
6612
+ if (options?.height) params.set("height", String(options.height));
6613
+ if (options?.fit) params.set("fit", options.fit);
6614
+ if (options?.format) params.set("format", options.format);
6615
+ if (options?.quality) params.set("quality", String(options.quality));
6616
+ const qs = params.toString();
6617
+ return `${this.client.getBaseUrl()}${this.basePath}/public/${photoId}/transform${qs ? `?${qs}` : ""}`;
6618
+ }
6499
6619
  /**
6500
6620
  * Get a transform URL optimized for the given display area.
6501
6621
  *
package/dist/index.mjs CHANGED
@@ -1960,6 +1960,24 @@ var DEFAULT_STALL_TIMEOUT_MS = 45e3;
1960
1960
  var SLOW_NETWORK_STALL_TIMEOUT_MS = 9e4;
1961
1961
  var MULTIPART_THRESHOLD = 8 * 1024 * 1024;
1962
1962
  var MULTIPART_THRESHOLD_SLOW = 4 * 1024 * 1024;
1963
+ function buildVisibilityWire(options) {
1964
+ if (!options) return {};
1965
+ if (options.visibility) {
1966
+ return {
1967
+ visibility: options.visibility,
1968
+ // Legacy field for old storage instances that haven't deployed
1969
+ // the tristate handler yet — omit `is_public` for the
1970
+ // `anonymous_visible` case so an old server that doesn't know
1971
+ // the new value at least falls through to its own default
1972
+ // rather than mis-treating it as `app_public`.
1973
+ ...options.visibility === "private" ? { is_public: false } : options.visibility === "app_public" ? { is_public: true } : {}
1974
+ };
1975
+ }
1976
+ if (typeof options.isPublic === "boolean") {
1977
+ return { is_public: options.isPublic };
1978
+ }
1979
+ return {};
1980
+ }
1963
1981
  var StorageService = class extends ServiceModule {
1964
1982
  constructor() {
1965
1983
  super(...arguments);
@@ -2041,6 +2059,42 @@ var StorageService = class extends ServiceModule {
2041
2059
  }
2042
2060
  return result;
2043
2061
  }
2062
+ /**
2063
+ * Upload a file as world-readable on the anonymous public CDN.
2064
+ *
2065
+ * Same browser→S3 pipeline as {@link upload}, but pins
2066
+ * `visibility: 'anonymous_visible'` — caller cannot opt out.
2067
+ *
2068
+ * Use this for media meant to render on logged-out marketing
2069
+ * pages, blog posts, embed snippets — anywhere a customer needs
2070
+ * to drop a URL into `<img src>` without an authenticated
2071
+ * session. For everything else (chat attachments, private
2072
+ * uploads, app-internal galleries) prefer {@link upload} or
2073
+ * {@link uploadPrivate}.
2074
+ *
2075
+ * **`cdn_url` may be `null` on the immediate response.** Storage
2076
+ * intentionally withholds the public CDN URL until the AV scan
2077
+ * has flipped to `clean` — exposing the URL pre-scan would let a
2078
+ * customer embed the bytes in a logged-out page before the
2079
+ * platform has verified them. The upload itself succeeds
2080
+ * regardless; consumers should check `result.data.cdn_url` and:
2081
+ * - if non-null → it's safe to publish
2082
+ * - if null → poll {@link getFileStatus} on a small backoff
2083
+ * until `urls.cdn_url` populates (or `scan.status` flips to
2084
+ * `threat` / `quarantined` / `error` — terminal failure)
2085
+ *
2086
+ * Requires the operator to have provisioned the anonymous
2087
+ * delivery bucket + CDN. When they haven't, the storage service
2088
+ * returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED` (an error
2089
+ * propagated through this helper) — it never silently demotes
2090
+ * to `app_public`.
2091
+ */
2092
+ async uploadAnonymous(file, options) {
2093
+ return this.upload(file, {
2094
+ ...options,
2095
+ visibility: "anonymous_visible"
2096
+ });
2097
+ }
2044
2098
  // --------------------------------------------------------------------------
2045
2099
  // Direct Upload (3-step with retry + stall)
2046
2100
  // --------------------------------------------------------------------------
@@ -2054,7 +2108,7 @@ var StorageService = class extends ServiceModule {
2054
2108
  filename,
2055
2109
  content_type: file.type || "application/octet-stream",
2056
2110
  size_bytes: file.size,
2057
- is_public: options?.isPublic ?? true,
2111
+ ...buildVisibilityWire(options),
2058
2112
  metadata: options?.metadata
2059
2113
  },
2060
2114
  requestOpts
@@ -2145,6 +2199,13 @@ var StorageService = class extends ServiceModule {
2145
2199
  content_type: d.content_type,
2146
2200
  size_bytes: d.size_bytes,
2147
2201
  url: d.url,
2202
+ // Surface visibility + cdn_url all the way out so callers
2203
+ // can branch on visibility without a follow-up getInfo()
2204
+ // round-trip. Anonymous-visible callers especially need
2205
+ // `cdn_url` here to render the image immediately.
2206
+ visibility: d.visibility,
2207
+ cdn_url: d.cdn_url,
2208
+ is_public: d.visibility ? d.visibility !== "private" : void 0,
2148
2209
  created_at: (/* @__PURE__ */ new Date()).toISOString()
2149
2210
  },
2150
2211
  error: null
@@ -2226,7 +2287,7 @@ var StorageService = class extends ServiceModule {
2226
2287
  filename,
2227
2288
  content_type: file.type || "application/octet-stream",
2228
2289
  size_bytes: file.size,
2229
- is_public: options?.isPublic ?? true,
2290
+ ...buildVisibilityWire(options),
2230
2291
  metadata: options?.metadata,
2231
2292
  chunk_size: options?.chunkSize,
2232
2293
  ...clientUploadKey ? { client_upload_key: clientUploadKey } : {}
@@ -2504,6 +2565,9 @@ var StorageService = class extends ServiceModule {
2504
2565
  content_type: d.content_type,
2505
2566
  size_bytes: d.size_bytes,
2506
2567
  url: d.url,
2568
+ visibility: d.visibility,
2569
+ cdn_url: d.cdn_url,
2570
+ is_public: d.visibility ? d.visibility !== "private" : void 0,
2507
2571
  created_at: (/* @__PURE__ */ new Date()).toISOString()
2508
2572
  },
2509
2573
  error: null
@@ -2541,7 +2605,7 @@ var StorageService = class extends ServiceModule {
2541
2605
  {
2542
2606
  filename,
2543
2607
  content_type: contentType,
2544
- is_public: options?.isPublic ?? true,
2608
+ ...buildVisibilityWire(options),
2545
2609
  expires_in: options?.expiresIn ?? 3600,
2546
2610
  size_bytes: options?.sizeBytes,
2547
2611
  metadata: options?.metadata
@@ -2588,7 +2652,16 @@ var StorageService = class extends ServiceModule {
2588
2652
  // --------------------------------------------------------------------------
2589
2653
  // Multipart Public API (for advanced/server-side usage)
2590
2654
  // --------------------------------------------------------------------------
2591
- /** Start a multipart upload session. */
2655
+ /**
2656
+ * Start a multipart upload session.
2657
+ *
2658
+ * Accepts both the typed `visibility` field (preferred) and the
2659
+ * legacy `is_public` boolean for back-compat. If both are sent the
2660
+ * storage service uses `visibility`. `'anonymous_visible'` requires
2661
+ * the operator to have provisioned the anonymous bucket — the
2662
+ * service returns 503 `ANONYMOUS_DELIVERY_NOT_CONFIGURED`
2663
+ * otherwise (the SDK never silently demotes).
2664
+ */
2592
2665
  async startMultipartUpload(params, requestOptions) {
2593
2666
  return this.post("/signed-url/multipart/start", params, requestOptions);
2594
2667
  }
@@ -2719,14 +2792,26 @@ var StorageService = class extends ServiceModule {
2719
2792
  return this._get(`/files/${fileId}/view-status`, options);
2720
2793
  }
2721
2794
  /**
2722
- * Update a file's visibility (public/private).
2723
- * Only the file owner can toggle this. Changes URL TTL — does not move the S3 object.
2724
- * Public files get 7-day signed URLs; private files get 1-hour signed URLs.
2795
+ * Update a file's visibility.
2796
+ *
2797
+ * Accepts either:
2798
+ * - a tri-state {@link Visibility} string (preferred), or
2799
+ * - a legacy boolean (`true` → `app_public`, `false` → `private`).
2800
+ *
2801
+ * Only the file owner / app member can toggle this. Same-bucket
2802
+ * transitions (`private` ↔ `app_public`) succeed and the service
2803
+ * keeps the legacy `is_public` column in sync via a DB trigger.
2804
+ * Cross-bucket transitions (any flip into or out of
2805
+ * `'anonymous_visible'`) currently return 409
2806
+ * `VISIBILITY_TRANSITION_UNSUPPORTED` — the bytes would need to
2807
+ * move between S3 buckets and that orchestration is not yet
2808
+ * shipped. Re-upload the file with the desired visibility instead.
2725
2809
  */
2726
- async updateVisibility(fileId, isPublic, options) {
2810
+ async updateVisibility(fileId, visibility, options) {
2811
+ const body = typeof visibility === "boolean" ? { is_public: visibility } : { visibility };
2727
2812
  return this.patch(
2728
2813
  `/files/${fileId}/visibility`,
2729
- { is_public: isPublic },
2814
+ body,
2730
2815
  options
2731
2816
  );
2732
2817
  }
@@ -6122,6 +6207,41 @@ var PhotoService = class extends ServiceModule {
6122
6207
  const qs = params.toString();
6123
6208
  return `${this.client.getBaseUrl()}${this.basePath}/${photoId}/transform${qs ? `?${qs}` : ""}`;
6124
6209
  }
6210
+ /**
6211
+ * Build an absolute URL for the **public** transform endpoint —
6212
+ * the unauthenticated path that serves transformed bytes for
6213
+ * `<img src>` use on logged-out marketing pages, blogs, embeds.
6214
+ *
6215
+ * The photo service refuses any photo that isn't:
6216
+ * - `visibility = 'anonymous_visible'` (the customer explicitly
6217
+ * opted into world-readable for this file at upload time)
6218
+ * - `scan_status = 'clean'` (no exception for pending/scanning)
6219
+ *
6220
+ * Anything else returns 404 — the endpoint refuses to disambiguate
6221
+ * "not found" from "not anonymous" so it can't be probed to
6222
+ * discover existence or visibility of private photos.
6223
+ *
6224
+ * Pair with {@link getTransformUrl} for the authenticated case:
6225
+ * customer apps that already have a session should keep using the
6226
+ * authed transform URL (which also handles `anonymous_visible`
6227
+ * photos transparently) — this URL is for cross-origin embedding.
6228
+ *
6229
+ * @example
6230
+ * ```tsx
6231
+ * // photo was uploaded with visibility: 'anonymous_visible'
6232
+ * <img src={sm.photo.getPublicTransformUrl(photoId, { width: 800 })} />
6233
+ * ```
6234
+ */
6235
+ getPublicTransformUrl(photoId, options) {
6236
+ const params = new URLSearchParams();
6237
+ if (options?.width) params.set("width", String(options.width));
6238
+ if (options?.height) params.set("height", String(options.height));
6239
+ if (options?.fit) params.set("fit", options.fit);
6240
+ if (options?.format) params.set("format", options.format);
6241
+ if (options?.quality) params.set("quality", String(options.quality));
6242
+ const qs = params.toString();
6243
+ return `${this.client.getBaseUrl()}${this.basePath}/public/${photoId}/transform${qs ? `?${qs}` : ""}`;
6244
+ }
6125
6245
  /**
6126
6246
  * Get a transform URL optimized for the given display area.
6127
6247
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.53",
3
+ "version": "0.0.55",
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",