@scalemule/sdk 0.0.54 → 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 +203 -7
- package/dist/index.d.ts +203 -7
- package/dist/index.js +129 -9
- package/dist/index.mjs +129 -9
- package/package.json +1 -1
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
1368
|
-
*
|
|
1369
|
-
*
|
|
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,
|
|
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
|
*
|
|
@@ -6666,4 +6862,4 @@ declare class ScaleMule {
|
|
|
6666
6862
|
getClient(): ScaleMuleClient;
|
|
6667
6863
|
}
|
|
6668
6864
|
|
|
6669
|
-
export { type AccountBalance, type AccountSwitcherPrivacy, AccountsService, type ActiveUsers, type ActivityItem, AgentAuthService, AgentModelsService, type AgentProfile, AgentProjectsService, type AgentResponse, type AgentSecurityPolicy, AgentSessionsService, type AgentSigningKey, type AgentToken, type AgentToolEntitlement, AgentToolsService, type Workspace as AgentWorkspace, AgentsService, type AggregateOptions, type AggregateResult, type AnalyticsEvent, AnalyticsService, type ApiError, type ApiKey, type ApiResponse, type Appeal, type Application, type Attachment, type Attendee, type AudioRegisterResult, AudioService, type AudioUploadViaStorageResult, type AuditLog, type AuthRegisterAgentRequest, type AuthRegisterAgentResponse, AuthService, type AuthSession, type AuthUser, type BackupCodes, BillingService, type CacheEntry, CacheService, type CalendarEvent, type CallParticipant, type CallSession, type CatalogEntry, CatalogService, type ChatMessage, type ChatReaction, ChatService, type ClaimResult, type Client, type ClientContext, type Collection, type Comment, CommunicationService, type CompletedPart, ComplianceService, type CompressionConfig, ConferenceService, type ConferenceSettings, type ConnectedAccount, type ConnectedAccountSubscription, type ConnectedSetupIntentResponse, type ConnectedSubscriptionListParams, type ConnectionStatus, type ContentFlag, type ContentPolicy, type Conversation, type CostReportDay, type CreateProjectInput as CreateCreatorProjectInput, type CreateFlagRequest, type CreateRuleRequest, type CreateSegmentRequest, type CreateSessionResponse, type CreateVariantRequest, type GenerationJob as CreatorJob, CreatorMakerService, type GenerationOutput as CreatorOutput, type CreatorProject, type CreatorUsage, type Credential, type CredentialScope, type Customer, type DataAccessPolicy, type DataExport, DataService, type DataSource, type DeadLetterJob, type DeviceInfo, type DirectoryUser, type DirectoryUserDetail, type DirectoryUsersListResponse, type Document, type ErrorCode, ErrorCodes, type EventAggregation, EventsService, type FileInfo, type FileStatus, type FlagAuditEntry, type FlagCheck, type FlagCondition, FlagContentService, type FlagDefinition, type FlagDetail, type FlagEnvironment, type FlagEvaluation, type FlagSegment, type FlagVariant, FlagsService, type FollowStatus, type FunctionExecution, type FunctionMetrics, FunctionsService, type Funnel, type FunnelConversion, type GdprRequest, type GenerateInput, type GrantInfo, type GraphEdge, type GraphNode, GraphService, IdentityService, type IdentityType, type IncomingRequestLike, type Invoice, type JobExecution, type JobStats, type JoinCallResponse, type KnownAccount, type KnownAccountDisplay, type Leaderboard, type LeaderboardEntry, LeaderboardService, type Like, type ListNotificationsParams, type Listing, ListingsService, type LogEntry, type LogInput, type LogQueryParams, type LogQueryResponse, type LogRecord, LoggerService, type LoginActivitySummary, type LoginDeviceInfo, type LoginHistoryEntry, type LoginRiskInfo, type MediaPolicy, type MessageCallback, type MessagePin, type MessageStatus, type MetricDataPoint, type MfaStatus, type Model, type ModelEntitlement, type ModelPricing, type ModelProvider, type UsageSummary as ModelUsageSummary, type MultipartCompleteResponse, type MultipartConfig, type MultipartPartUrl, type MultipartPartUrlsResponse, type MultipartStartResponse, type NetworkClass, type Notification, type NotificationListResponse, NotificationsService, type OAuthProvider, type OAuthUrl, OrchestratorService, PHOTO_BREAKPOINTS, type PaginatedResponse, type PaginationMetadata, type PaginationParams, type PartResult, type PartUrl, type Participant, type Payment, type PaymentListParams, type PaymentMethod, type PaymentStatusResponse, type Payout, type PayoutSchedule, type PermissionCheck, type PermissionMatrix, PermissionsService, type PhotoInfo, PhotoService, type PinnedMessagesResponse, type Pipeline, type PipelineVersion, type Policy, type PresenceCallback, type PresenceEvent, type PresignedUploadResponse, type Price, type Product, type Project, type ProjectDocument, type ProjectGrant, type ProjectMember, type PushApiFetcher, type PushPreferences, type PushSettings, type PushSubscriptionInfo, type PushToken, type PushTokenAssociationResult, type PushTopic, type QueryFilter, type QueryOptions, type QuerySort, type QueueJob, QueueService, type ReadStatus, RealtimeService, type RedeemResult, type ReferralAnalytics, type ReferralCampaign, type ReferralProfile, type ReferralStats, ReferralsService, type Refund, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterPushTokenData, type RequestOptions, type ResolvedReferral, type ResumeSession, type Role, type RuntimeTemplate, type RuntimeTemplateVersion, type S3MultipartOptions, type S3MultipartResult, type S3SingleUploadOptions, type S3SingleUploadResult, type S3UploadProgress, ScaleMule, ScaleMuleClient, type ScaleMuleConfig, type SchedulerJob, SchedulerService, type SearchResult, SearchService, type SearchUsersParams, type SecurityLayers, type ServerlessFunction, type ServiceHealth, ServiceModule, type Session, type SessionArtifact, type SessionInfo, type SessionLog, type SessionPoolEntry, type Severity, type ShareLink, type ShortestPathResult, type SignedUrlResponse, type SocialPost, SocialService, type SocialUser, type SsoConfig, type StatusCallback, type StorageAdapter, StorageService, type StorageSettings, type StrategyResult, type StylePreset, type SubmitResult, type Subscription, type TargetingRule, type Task, type TaskAttempt, type TaskTransition, type Team, type TeamInvitation, type TeamMember, TeamsService, type TelemetryPayload, type Tool, type ToolCapability, type ToolIntegration, type TopEvent, type TotpSetup, type Transaction, type TransactionListParams, type TransactionSummary, type TransactionSummaryParams, type Transfer, type TransformOptions, type TransformResult, type TraversalResult, type TtsAccessMode, type TtsAudioInfo, type TtsJobStatus, type TtsListVoicesParams, TtsService, type TtsSpeechMetadata, type TtsSpeechProfile, type TtsSynthesizeParams, type TtsSynthesizeQueuedResult, type TtsSynthesizeReadyResult, type TtsSynthesizeResult, type TtsVoice, type TtsVoicesResponse, type UnreadCountResponse, type UpdateFlagRequest, type UpdateRuleRequest, type UpdateSegmentRequest, type UpdateVariantRequest, type UploadCompleteResponse, type UploadEngineConfig, type UploadFailureReport, type UploadFailureReportResponse, type UploadOptions, type UploadPlan, UploadResumeStore, type UploadStrategy, UploadTelemetry, type UploadTelemetryConfig, type UploadTelemetryEvent, type UpsertEnvironmentRequest, type UsageRecord, type UsageSummary$1 as UsageSummary, type UserRank, type VideoInfo, VideoService, type VideoUploadOptions,
|
|
6865
|
+
export { type AccountBalance, type AccountSwitcherPrivacy, AccountsService, type ActiveUsers, type ActivityItem, AgentAuthService, AgentModelsService, type AgentProfile, AgentProjectsService, type AgentResponse, type AgentSecurityPolicy, AgentSessionsService, type AgentSigningKey, type AgentToken, type AgentToolEntitlement, AgentToolsService, type Workspace as AgentWorkspace, AgentsService, type AggregateOptions, type AggregateResult, type AnalyticsEvent, AnalyticsService, type ApiError, type ApiKey, type ApiResponse, type Appeal, type Application, type Attachment, type Attendee, type AudioRegisterResult, AudioService, type AudioUploadViaStorageResult, type AuditLog, type AuthRegisterAgentRequest, type AuthRegisterAgentResponse, AuthService, type AuthSession, type AuthUser, type BackupCodes, BillingService, type CacheEntry, CacheService, type CalendarEvent, type CallParticipant, type CallSession, type CatalogEntry, CatalogService, type ChatMessage, type ChatReaction, ChatService, type ClaimResult, type Client, type ClientContext, type Collection, type Comment, CommunicationService, type CompletedPart, ComplianceService, type CompressionConfig, ConferenceService, type ConferenceSettings, type ConnectedAccount, type ConnectedAccountSubscription, type ConnectedSetupIntentResponse, type ConnectedSubscriptionListParams, type ConnectionStatus, type ContentFlag, type ContentPolicy, type Conversation, type CostReportDay, type CreateProjectInput as CreateCreatorProjectInput, type CreateFlagRequest, type CreateRuleRequest, type CreateSegmentRequest, type CreateSessionResponse, type CreateVariantRequest, type GenerationJob as CreatorJob, CreatorMakerService, type GenerationOutput as CreatorOutput, type CreatorProject, type CreatorUsage, type Credential, type CredentialScope, type Customer, type DataAccessPolicy, type DataExport, DataService, type DataSource, type DeadLetterJob, type DeviceInfo, type DirectoryUser, type DirectoryUserDetail, type DirectoryUsersListResponse, type Document, type ErrorCode, ErrorCodes, type EventAggregation, EventsService, type FileInfo, type FileStatus, type FlagAuditEntry, type FlagCheck, type FlagCondition, FlagContentService, type FlagDefinition, type FlagDetail, type FlagEnvironment, type FlagEvaluation, type FlagSegment, type FlagVariant, FlagsService, type FollowStatus, type FunctionExecution, type FunctionMetrics, FunctionsService, type Funnel, type FunnelConversion, type GdprRequest, type GenerateInput, type GrantInfo, type GraphEdge, type GraphNode, GraphService, IdentityService, type IdentityType, type IncomingRequestLike, type Invoice, type JobExecution, type JobStats, type JoinCallResponse, type KnownAccount, type KnownAccountDisplay, type Leaderboard, type LeaderboardEntry, LeaderboardService, type Like, type ListNotificationsParams, type Listing, ListingsService, type LogEntry, type LogInput, type LogQueryParams, type LogQueryResponse, type LogRecord, LoggerService, type LoginActivitySummary, type LoginDeviceInfo, type LoginHistoryEntry, type LoginRiskInfo, type MediaPolicy, type MessageCallback, type MessagePin, type MessageStatus, type MetricDataPoint, type MfaStatus, type Model, type ModelEntitlement, type ModelPricing, type ModelProvider, type UsageSummary as ModelUsageSummary, type MultipartCompleteResponse, type MultipartConfig, type MultipartPartUrl, type MultipartPartUrlsResponse, type MultipartStartResponse, type NetworkClass, type Notification, type NotificationListResponse, NotificationsService, type OAuthProvider, type OAuthUrl, OrchestratorService, PHOTO_BREAKPOINTS, type PaginatedResponse, type PaginationMetadata, type PaginationParams, type PartResult, type PartUrl, type Participant, type Payment, type PaymentListParams, type PaymentMethod, type PaymentStatusResponse, type Payout, type PayoutSchedule, type PermissionCheck, type PermissionMatrix, PermissionsService, type PhotoInfo, PhotoService, type PinnedMessagesResponse, type Pipeline, type PipelineVersion, type Policy, type PresenceCallback, type PresenceEvent, type PresignedUploadResponse, type Price, type Product, type Project, type ProjectDocument, type ProjectGrant, type ProjectMember, type PushApiFetcher, type PushPreferences, type PushSettings, type PushSubscriptionInfo, type PushToken, type PushTokenAssociationResult, type PushTopic, type QueryFilter, type QueryOptions, type QuerySort, type QueueJob, QueueService, type ReadStatus, RealtimeService, type RedeemResult, type ReferralAnalytics, type ReferralCampaign, type ReferralProfile, type ReferralStats, ReferralsService, type Refund, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterPushTokenData, type RequestOptions, type ResolvedReferral, type ResumeSession, type Role, type RuntimeTemplate, type RuntimeTemplateVersion, type S3MultipartOptions, type S3MultipartResult, type S3SingleUploadOptions, type S3SingleUploadResult, type S3UploadProgress, ScaleMule, ScaleMuleClient, type ScaleMuleConfig, type SchedulerJob, SchedulerService, type SearchResult, SearchService, type SearchUsersParams, type SecurityLayers, type ServerlessFunction, type ServiceHealth, ServiceModule, type Session, type SessionArtifact, type SessionInfo, type SessionLog, type SessionPoolEntry, type Severity, type ShareLink, type ShortestPathResult, type SignedUrlResponse, type SocialPost, SocialService, type SocialUser, type SsoConfig, type StatusCallback, type StorageAdapter, StorageService, type StorageSettings, type StrategyResult, type StylePreset, type SubmitResult, type Subscription, type TargetingRule, type Task, type TaskAttempt, type TaskTransition, type Team, type TeamInvitation, type TeamMember, TeamsService, type TelemetryPayload, type Tool, type ToolCapability, type ToolIntegration, type TopEvent, type TotpSetup, type Transaction, type TransactionListParams, type TransactionSummary, type TransactionSummaryParams, type Transfer, type TransformOptions, type TransformResult, type TraversalResult, type TtsAccessMode, type TtsAudioInfo, type TtsJobStatus, type TtsListVoicesParams, TtsService, type TtsSpeechMetadata, type TtsSpeechProfile, type TtsSynthesizeParams, type TtsSynthesizeQueuedResult, type TtsSynthesizeReadyResult, type TtsSynthesizeResult, type TtsVoice, type TtsVoicesResponse, type UnreadCountResponse, type UpdateFlagRequest, type UpdateRuleRequest, type UpdateSegmentRequest, type UpdateVariantRequest, type UploadCompleteResponse, type UploadEngineConfig, type UploadFailureReport, type UploadFailureReportResponse, type UploadOptions, type UploadPlan, UploadResumeStore, type UploadStrategy, UploadTelemetry, type UploadTelemetryConfig, type UploadTelemetryEvent, type UpsertEnvironmentRequest, type UsageRecord, type UsageSummary$1 as UsageSummary, type UserRank, type VideoInfo, VideoService, type VideoUploadOptions, WEB_PUSH_SERVICE_WORKER, WebPushManager, type WebPushManagerOptions, type WebPushSubscriptionData, type Webhook, WebhooksService, type WebrtcStats, type Workflow, type WorkflowExecution, type Workspace$1 as Workspace, type WorkspaceInvitation, type WorkspaceMember, WorkspacesService, buildClientContextHeaders, calculateTotalParts, canPerform, createUploadPlan, ScaleMule as default, detectNetworkClass, extractClientContext, generateUploadSessionId, getMeasuredBandwidthMbps, getPartRange, hasMinRoleLevel, resolveStrategy, uploadMultipartToS3, uploadSingleToS3, validateIP };
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
1368
|
-
*
|
|
1369
|
-
*
|
|
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,
|
|
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
|
*
|
|
@@ -6666,4 +6862,4 @@ declare class ScaleMule {
|
|
|
6666
6862
|
getClient(): ScaleMuleClient;
|
|
6667
6863
|
}
|
|
6668
6864
|
|
|
6669
|
-
export { type AccountBalance, type AccountSwitcherPrivacy, AccountsService, type ActiveUsers, type ActivityItem, AgentAuthService, AgentModelsService, type AgentProfile, AgentProjectsService, type AgentResponse, type AgentSecurityPolicy, AgentSessionsService, type AgentSigningKey, type AgentToken, type AgentToolEntitlement, AgentToolsService, type Workspace as AgentWorkspace, AgentsService, type AggregateOptions, type AggregateResult, type AnalyticsEvent, AnalyticsService, type ApiError, type ApiKey, type ApiResponse, type Appeal, type Application, type Attachment, type Attendee, type AudioRegisterResult, AudioService, type AudioUploadViaStorageResult, type AuditLog, type AuthRegisterAgentRequest, type AuthRegisterAgentResponse, AuthService, type AuthSession, type AuthUser, type BackupCodes, BillingService, type CacheEntry, CacheService, type CalendarEvent, type CallParticipant, type CallSession, type CatalogEntry, CatalogService, type ChatMessage, type ChatReaction, ChatService, type ClaimResult, type Client, type ClientContext, type Collection, type Comment, CommunicationService, type CompletedPart, ComplianceService, type CompressionConfig, ConferenceService, type ConferenceSettings, type ConnectedAccount, type ConnectedAccountSubscription, type ConnectedSetupIntentResponse, type ConnectedSubscriptionListParams, type ConnectionStatus, type ContentFlag, type ContentPolicy, type Conversation, type CostReportDay, type CreateProjectInput as CreateCreatorProjectInput, type CreateFlagRequest, type CreateRuleRequest, type CreateSegmentRequest, type CreateSessionResponse, type CreateVariantRequest, type GenerationJob as CreatorJob, CreatorMakerService, type GenerationOutput as CreatorOutput, type CreatorProject, type CreatorUsage, type Credential, type CredentialScope, type Customer, type DataAccessPolicy, type DataExport, DataService, type DataSource, type DeadLetterJob, type DeviceInfo, type DirectoryUser, type DirectoryUserDetail, type DirectoryUsersListResponse, type Document, type ErrorCode, ErrorCodes, type EventAggregation, EventsService, type FileInfo, type FileStatus, type FlagAuditEntry, type FlagCheck, type FlagCondition, FlagContentService, type FlagDefinition, type FlagDetail, type FlagEnvironment, type FlagEvaluation, type FlagSegment, type FlagVariant, FlagsService, type FollowStatus, type FunctionExecution, type FunctionMetrics, FunctionsService, type Funnel, type FunnelConversion, type GdprRequest, type GenerateInput, type GrantInfo, type GraphEdge, type GraphNode, GraphService, IdentityService, type IdentityType, type IncomingRequestLike, type Invoice, type JobExecution, type JobStats, type JoinCallResponse, type KnownAccount, type KnownAccountDisplay, type Leaderboard, type LeaderboardEntry, LeaderboardService, type Like, type ListNotificationsParams, type Listing, ListingsService, type LogEntry, type LogInput, type LogQueryParams, type LogQueryResponse, type LogRecord, LoggerService, type LoginActivitySummary, type LoginDeviceInfo, type LoginHistoryEntry, type LoginRiskInfo, type MediaPolicy, type MessageCallback, type MessagePin, type MessageStatus, type MetricDataPoint, type MfaStatus, type Model, type ModelEntitlement, type ModelPricing, type ModelProvider, type UsageSummary as ModelUsageSummary, type MultipartCompleteResponse, type MultipartConfig, type MultipartPartUrl, type MultipartPartUrlsResponse, type MultipartStartResponse, type NetworkClass, type Notification, type NotificationListResponse, NotificationsService, type OAuthProvider, type OAuthUrl, OrchestratorService, PHOTO_BREAKPOINTS, type PaginatedResponse, type PaginationMetadata, type PaginationParams, type PartResult, type PartUrl, type Participant, type Payment, type PaymentListParams, type PaymentMethod, type PaymentStatusResponse, type Payout, type PayoutSchedule, type PermissionCheck, type PermissionMatrix, PermissionsService, type PhotoInfo, PhotoService, type PinnedMessagesResponse, type Pipeline, type PipelineVersion, type Policy, type PresenceCallback, type PresenceEvent, type PresignedUploadResponse, type Price, type Product, type Project, type ProjectDocument, type ProjectGrant, type ProjectMember, type PushApiFetcher, type PushPreferences, type PushSettings, type PushSubscriptionInfo, type PushToken, type PushTokenAssociationResult, type PushTopic, type QueryFilter, type QueryOptions, type QuerySort, type QueueJob, QueueService, type ReadStatus, RealtimeService, type RedeemResult, type ReferralAnalytics, type ReferralCampaign, type ReferralProfile, type ReferralStats, ReferralsService, type Refund, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterPushTokenData, type RequestOptions, type ResolvedReferral, type ResumeSession, type Role, type RuntimeTemplate, type RuntimeTemplateVersion, type S3MultipartOptions, type S3MultipartResult, type S3SingleUploadOptions, type S3SingleUploadResult, type S3UploadProgress, ScaleMule, ScaleMuleClient, type ScaleMuleConfig, type SchedulerJob, SchedulerService, type SearchResult, SearchService, type SearchUsersParams, type SecurityLayers, type ServerlessFunction, type ServiceHealth, ServiceModule, type Session, type SessionArtifact, type SessionInfo, type SessionLog, type SessionPoolEntry, type Severity, type ShareLink, type ShortestPathResult, type SignedUrlResponse, type SocialPost, SocialService, type SocialUser, type SsoConfig, type StatusCallback, type StorageAdapter, StorageService, type StorageSettings, type StrategyResult, type StylePreset, type SubmitResult, type Subscription, type TargetingRule, type Task, type TaskAttempt, type TaskTransition, type Team, type TeamInvitation, type TeamMember, TeamsService, type TelemetryPayload, type Tool, type ToolCapability, type ToolIntegration, type TopEvent, type TotpSetup, type Transaction, type TransactionListParams, type TransactionSummary, type TransactionSummaryParams, type Transfer, type TransformOptions, type TransformResult, type TraversalResult, type TtsAccessMode, type TtsAudioInfo, type TtsJobStatus, type TtsListVoicesParams, TtsService, type TtsSpeechMetadata, type TtsSpeechProfile, type TtsSynthesizeParams, type TtsSynthesizeQueuedResult, type TtsSynthesizeReadyResult, type TtsSynthesizeResult, type TtsVoice, type TtsVoicesResponse, type UnreadCountResponse, type UpdateFlagRequest, type UpdateRuleRequest, type UpdateSegmentRequest, type UpdateVariantRequest, type UploadCompleteResponse, type UploadEngineConfig, type UploadFailureReport, type UploadFailureReportResponse, type UploadOptions, type UploadPlan, UploadResumeStore, type UploadStrategy, UploadTelemetry, type UploadTelemetryConfig, type UploadTelemetryEvent, type UpsertEnvironmentRequest, type UsageRecord, type UsageSummary$1 as UsageSummary, type UserRank, type VideoInfo, VideoService, type VideoUploadOptions,
|
|
6865
|
+
export { type AccountBalance, type AccountSwitcherPrivacy, AccountsService, type ActiveUsers, type ActivityItem, AgentAuthService, AgentModelsService, type AgentProfile, AgentProjectsService, type AgentResponse, type AgentSecurityPolicy, AgentSessionsService, type AgentSigningKey, type AgentToken, type AgentToolEntitlement, AgentToolsService, type Workspace as AgentWorkspace, AgentsService, type AggregateOptions, type AggregateResult, type AnalyticsEvent, AnalyticsService, type ApiError, type ApiKey, type ApiResponse, type Appeal, type Application, type Attachment, type Attendee, type AudioRegisterResult, AudioService, type AudioUploadViaStorageResult, type AuditLog, type AuthRegisterAgentRequest, type AuthRegisterAgentResponse, AuthService, type AuthSession, type AuthUser, type BackupCodes, BillingService, type CacheEntry, CacheService, type CalendarEvent, type CallParticipant, type CallSession, type CatalogEntry, CatalogService, type ChatMessage, type ChatReaction, ChatService, type ClaimResult, type Client, type ClientContext, type Collection, type Comment, CommunicationService, type CompletedPart, ComplianceService, type CompressionConfig, ConferenceService, type ConferenceSettings, type ConnectedAccount, type ConnectedAccountSubscription, type ConnectedSetupIntentResponse, type ConnectedSubscriptionListParams, type ConnectionStatus, type ContentFlag, type ContentPolicy, type Conversation, type CostReportDay, type CreateProjectInput as CreateCreatorProjectInput, type CreateFlagRequest, type CreateRuleRequest, type CreateSegmentRequest, type CreateSessionResponse, type CreateVariantRequest, type GenerationJob as CreatorJob, CreatorMakerService, type GenerationOutput as CreatorOutput, type CreatorProject, type CreatorUsage, type Credential, type CredentialScope, type Customer, type DataAccessPolicy, type DataExport, DataService, type DataSource, type DeadLetterJob, type DeviceInfo, type DirectoryUser, type DirectoryUserDetail, type DirectoryUsersListResponse, type Document, type ErrorCode, ErrorCodes, type EventAggregation, EventsService, type FileInfo, type FileStatus, type FlagAuditEntry, type FlagCheck, type FlagCondition, FlagContentService, type FlagDefinition, type FlagDetail, type FlagEnvironment, type FlagEvaluation, type FlagSegment, type FlagVariant, FlagsService, type FollowStatus, type FunctionExecution, type FunctionMetrics, FunctionsService, type Funnel, type FunnelConversion, type GdprRequest, type GenerateInput, type GrantInfo, type GraphEdge, type GraphNode, GraphService, IdentityService, type IdentityType, type IncomingRequestLike, type Invoice, type JobExecution, type JobStats, type JoinCallResponse, type KnownAccount, type KnownAccountDisplay, type Leaderboard, type LeaderboardEntry, LeaderboardService, type Like, type ListNotificationsParams, type Listing, ListingsService, type LogEntry, type LogInput, type LogQueryParams, type LogQueryResponse, type LogRecord, LoggerService, type LoginActivitySummary, type LoginDeviceInfo, type LoginHistoryEntry, type LoginRiskInfo, type MediaPolicy, type MessageCallback, type MessagePin, type MessageStatus, type MetricDataPoint, type MfaStatus, type Model, type ModelEntitlement, type ModelPricing, type ModelProvider, type UsageSummary as ModelUsageSummary, type MultipartCompleteResponse, type MultipartConfig, type MultipartPartUrl, type MultipartPartUrlsResponse, type MultipartStartResponse, type NetworkClass, type Notification, type NotificationListResponse, NotificationsService, type OAuthProvider, type OAuthUrl, OrchestratorService, PHOTO_BREAKPOINTS, type PaginatedResponse, type PaginationMetadata, type PaginationParams, type PartResult, type PartUrl, type Participant, type Payment, type PaymentListParams, type PaymentMethod, type PaymentStatusResponse, type Payout, type PayoutSchedule, type PermissionCheck, type PermissionMatrix, PermissionsService, type PhotoInfo, PhotoService, type PinnedMessagesResponse, type Pipeline, type PipelineVersion, type Policy, type PresenceCallback, type PresenceEvent, type PresignedUploadResponse, type Price, type Product, type Project, type ProjectDocument, type ProjectGrant, type ProjectMember, type PushApiFetcher, type PushPreferences, type PushSettings, type PushSubscriptionInfo, type PushToken, type PushTokenAssociationResult, type PushTopic, type QueryFilter, type QueryOptions, type QuerySort, type QueueJob, QueueService, type ReadStatus, RealtimeService, type RedeemResult, type ReferralAnalytics, type ReferralCampaign, type ReferralProfile, type ReferralStats, ReferralsService, type Refund, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterPushTokenData, type RequestOptions, type ResolvedReferral, type ResumeSession, type Role, type RuntimeTemplate, type RuntimeTemplateVersion, type S3MultipartOptions, type S3MultipartResult, type S3SingleUploadOptions, type S3SingleUploadResult, type S3UploadProgress, ScaleMule, ScaleMuleClient, type ScaleMuleConfig, type SchedulerJob, SchedulerService, type SearchResult, SearchService, type SearchUsersParams, type SecurityLayers, type ServerlessFunction, type ServiceHealth, ServiceModule, type Session, type SessionArtifact, type SessionInfo, type SessionLog, type SessionPoolEntry, type Severity, type ShareLink, type ShortestPathResult, type SignedUrlResponse, type SocialPost, SocialService, type SocialUser, type SsoConfig, type StatusCallback, type StorageAdapter, StorageService, type StorageSettings, type StrategyResult, type StylePreset, type SubmitResult, type Subscription, type TargetingRule, type Task, type TaskAttempt, type TaskTransition, type Team, type TeamInvitation, type TeamMember, TeamsService, type TelemetryPayload, type Tool, type ToolCapability, type ToolIntegration, type TopEvent, type TotpSetup, type Transaction, type TransactionListParams, type TransactionSummary, type TransactionSummaryParams, type Transfer, type TransformOptions, type TransformResult, type TraversalResult, type TtsAccessMode, type TtsAudioInfo, type TtsJobStatus, type TtsListVoicesParams, TtsService, type TtsSpeechMetadata, type TtsSpeechProfile, type TtsSynthesizeParams, type TtsSynthesizeQueuedResult, type TtsSynthesizeReadyResult, type TtsSynthesizeResult, type TtsVoice, type TtsVoicesResponse, type UnreadCountResponse, type UpdateFlagRequest, type UpdateRuleRequest, type UpdateSegmentRequest, type UpdateVariantRequest, type UploadCompleteResponse, type UploadEngineConfig, type UploadFailureReport, type UploadFailureReportResponse, type UploadOptions, type UploadPlan, UploadResumeStore, type UploadStrategy, UploadTelemetry, type UploadTelemetryConfig, type UploadTelemetryEvent, type UpsertEnvironmentRequest, type UsageRecord, type UsageSummary$1 as UsageSummary, type UserRank, type VideoInfo, VideoService, type VideoUploadOptions, WEB_PUSH_SERVICE_WORKER, WebPushManager, type WebPushManagerOptions, type WebPushSubscriptionData, type Webhook, WebhooksService, type WebrtcStats, type Workflow, type WorkflowExecution, type Workspace$1 as Workspace, type WorkspaceInvitation, type WorkspaceMember, WorkspacesService, buildClientContextHeaders, calculateTotalParts, canPerform, createUploadPlan, ScaleMule as default, detectNetworkClass, extractClientContext, generateUploadSessionId, getMeasuredBandwidthMbps, getPartRange, hasMinRoleLevel, resolveStrategy, uploadMultipartToS3, uploadSingleToS3, validateIP };
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
|
3094
|
-
*
|
|
3095
|
-
*
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
|
2723
|
-
*
|
|
2724
|
-
*
|
|
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,
|
|
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
|
-
|
|
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
|
*
|