@scalemule/sdk 0.0.37 → 0.0.38
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 +83 -0
- package/dist/index.d.ts +83 -0
- package/dist/index.js +124 -3
- package/dist/index.mjs +124 -3
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -1134,6 +1134,23 @@ declare class StorageService extends ServiceModule {
|
|
|
1134
1134
|
* @returns The completed file record with id, url, etc.
|
|
1135
1135
|
*/
|
|
1136
1136
|
upload(file: File | Blob, options?: UploadOptions): Promise<ApiResponse<FileInfo>>;
|
|
1137
|
+
/**
|
|
1138
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
1139
|
+
*
|
|
1140
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
1141
|
+
* - `is_public: false` — caller cannot opt out
|
|
1142
|
+
* - no client-side compression — preserve the original bytes
|
|
1143
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
1144
|
+
*
|
|
1145
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
1146
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
1147
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
1148
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
1149
|
+
*
|
|
1150
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
1151
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
1152
|
+
*/
|
|
1153
|
+
uploadPrivate(file: File | Blob, options?: Omit<UploadOptions, 'isPublic' | 'skipCompression'>): Promise<ApiResponse<FileInfo>>;
|
|
1137
1154
|
private uploadDirect;
|
|
1138
1155
|
private uploadMultipart;
|
|
1139
1156
|
private abortMultipart;
|
|
@@ -4222,8 +4239,39 @@ interface TransformOptions {
|
|
|
4222
4239
|
* URLs built with these sizes + fit=cover get instant cache hits (no server-side transform).
|
|
4223
4240
|
*/
|
|
4224
4241
|
declare const PHOTO_BREAKPOINTS: readonly [36, 150, 320, 640, 1080];
|
|
4242
|
+
/** Result of {@link PhotoService.uploadViaStorage}. */
|
|
4243
|
+
interface UploadViaStorageResult {
|
|
4244
|
+
/** Storage file_id — pass this to chat-message attachment metadata. */
|
|
4245
|
+
file_id: string;
|
|
4246
|
+
/**
|
|
4247
|
+
* Photo service's photo_id. Use with `getTransformUrl()` /
|
|
4248
|
+
* `getOptimalUrl()` to fetch responsive variants. `null` when register
|
|
4249
|
+
* failed after a successful storage upload (the file_id is still usable
|
|
4250
|
+
* as a generic storage file).
|
|
4251
|
+
*/
|
|
4252
|
+
photo_id: string | null;
|
|
4253
|
+
/**
|
|
4254
|
+
* Short-lived signed URL to the original bytes — usable immediately on the
|
|
4255
|
+
* recipient side, before optimization completes.
|
|
4256
|
+
*/
|
|
4257
|
+
original_view_url: string | null;
|
|
4258
|
+
/**
|
|
4259
|
+
* Resolves once the optimization worker finishes (or times out at 10s).
|
|
4260
|
+
* On resolution: a transform URL pointing at the largest pre-cached
|
|
4261
|
+
* breakpoint. On timeout: `null` — caller should fall back to
|
|
4262
|
+
* `getTransformUrl()` which uses the on-demand transform path.
|
|
4263
|
+
*/
|
|
4264
|
+
optimized_url_promise: Promise<string | null>;
|
|
4265
|
+
}
|
|
4225
4266
|
declare class PhotoService extends ServiceModule {
|
|
4267
|
+
private readonly storage;
|
|
4226
4268
|
protected basePath: string;
|
|
4269
|
+
/**
|
|
4270
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
4271
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
4272
|
+
* instantiate `PhotoService` directly.
|
|
4273
|
+
*/
|
|
4274
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
4227
4275
|
upload(file: File | Blob, uploadOptions?: {
|
|
4228
4276
|
metadata?: Record<string, unknown>;
|
|
4229
4277
|
onProgress?: (progress: number) => void;
|
|
@@ -4311,6 +4359,41 @@ declare class PhotoService extends ServiceModule {
|
|
|
4311
4359
|
fileId: string;
|
|
4312
4360
|
userId?: string;
|
|
4313
4361
|
}, requestOptions?: RequestOptions): Promise<ApiResponse<PhotoInfo>>;
|
|
4362
|
+
/**
|
|
4363
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
4364
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
4365
|
+
*
|
|
4366
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
4367
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
4368
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
4369
|
+
* usable URLs.
|
|
4370
|
+
*
|
|
4371
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
4372
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
4373
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
4374
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
4375
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
4376
|
+
* subscription.
|
|
4377
|
+
*
|
|
4378
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
4379
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
4380
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
4381
|
+
* `optimized_url_promise` to `null`.
|
|
4382
|
+
*/
|
|
4383
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
4384
|
+
userId?: string;
|
|
4385
|
+
filename?: string;
|
|
4386
|
+
metadata?: Record<string, unknown>;
|
|
4387
|
+
onProgress?: (progress: number) => void;
|
|
4388
|
+
signal?: AbortSignal;
|
|
4389
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<UploadViaStorageResult>>;
|
|
4390
|
+
/**
|
|
4391
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
4392
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
4393
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
4394
|
+
* which uses the on-demand transform path).
|
|
4395
|
+
*/
|
|
4396
|
+
private pollOptimizationComplete;
|
|
4314
4397
|
/** @deprecated Use upload() instead */
|
|
4315
4398
|
uploadPhoto(file: File | Blob, options?: {
|
|
4316
4399
|
metadata?: Record<string, unknown>;
|
package/dist/index.d.ts
CHANGED
|
@@ -1134,6 +1134,23 @@ declare class StorageService extends ServiceModule {
|
|
|
1134
1134
|
* @returns The completed file record with id, url, etc.
|
|
1135
1135
|
*/
|
|
1136
1136
|
upload(file: File | Blob, options?: UploadOptions): Promise<ApiResponse<FileInfo>>;
|
|
1137
|
+
/**
|
|
1138
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
1139
|
+
*
|
|
1140
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
1141
|
+
* - `is_public: false` — caller cannot opt out
|
|
1142
|
+
* - no client-side compression — preserve the original bytes
|
|
1143
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
1144
|
+
*
|
|
1145
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
1146
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
1147
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
1148
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
1149
|
+
*
|
|
1150
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
1151
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
1152
|
+
*/
|
|
1153
|
+
uploadPrivate(file: File | Blob, options?: Omit<UploadOptions, 'isPublic' | 'skipCompression'>): Promise<ApiResponse<FileInfo>>;
|
|
1137
1154
|
private uploadDirect;
|
|
1138
1155
|
private uploadMultipart;
|
|
1139
1156
|
private abortMultipart;
|
|
@@ -4222,8 +4239,39 @@ interface TransformOptions {
|
|
|
4222
4239
|
* URLs built with these sizes + fit=cover get instant cache hits (no server-side transform).
|
|
4223
4240
|
*/
|
|
4224
4241
|
declare const PHOTO_BREAKPOINTS: readonly [36, 150, 320, 640, 1080];
|
|
4242
|
+
/** Result of {@link PhotoService.uploadViaStorage}. */
|
|
4243
|
+
interface UploadViaStorageResult {
|
|
4244
|
+
/** Storage file_id — pass this to chat-message attachment metadata. */
|
|
4245
|
+
file_id: string;
|
|
4246
|
+
/**
|
|
4247
|
+
* Photo service's photo_id. Use with `getTransformUrl()` /
|
|
4248
|
+
* `getOptimalUrl()` to fetch responsive variants. `null` when register
|
|
4249
|
+
* failed after a successful storage upload (the file_id is still usable
|
|
4250
|
+
* as a generic storage file).
|
|
4251
|
+
*/
|
|
4252
|
+
photo_id: string | null;
|
|
4253
|
+
/**
|
|
4254
|
+
* Short-lived signed URL to the original bytes — usable immediately on the
|
|
4255
|
+
* recipient side, before optimization completes.
|
|
4256
|
+
*/
|
|
4257
|
+
original_view_url: string | null;
|
|
4258
|
+
/**
|
|
4259
|
+
* Resolves once the optimization worker finishes (or times out at 10s).
|
|
4260
|
+
* On resolution: a transform URL pointing at the largest pre-cached
|
|
4261
|
+
* breakpoint. On timeout: `null` — caller should fall back to
|
|
4262
|
+
* `getTransformUrl()` which uses the on-demand transform path.
|
|
4263
|
+
*/
|
|
4264
|
+
optimized_url_promise: Promise<string | null>;
|
|
4265
|
+
}
|
|
4225
4266
|
declare class PhotoService extends ServiceModule {
|
|
4267
|
+
private readonly storage;
|
|
4226
4268
|
protected basePath: string;
|
|
4269
|
+
/**
|
|
4270
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
4271
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
4272
|
+
* instantiate `PhotoService` directly.
|
|
4273
|
+
*/
|
|
4274
|
+
constructor(client: ScaleMuleClient, storage: StorageService);
|
|
4227
4275
|
upload(file: File | Blob, uploadOptions?: {
|
|
4228
4276
|
metadata?: Record<string, unknown>;
|
|
4229
4277
|
onProgress?: (progress: number) => void;
|
|
@@ -4311,6 +4359,41 @@ declare class PhotoService extends ServiceModule {
|
|
|
4311
4359
|
fileId: string;
|
|
4312
4360
|
userId?: string;
|
|
4313
4361
|
}, requestOptions?: RequestOptions): Promise<ApiResponse<PhotoInfo>>;
|
|
4362
|
+
/**
|
|
4363
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
4364
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
4365
|
+
*
|
|
4366
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
4367
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
4368
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
4369
|
+
* usable URLs.
|
|
4370
|
+
*
|
|
4371
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
4372
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
4373
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
4374
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
4375
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
4376
|
+
* subscription.
|
|
4377
|
+
*
|
|
4378
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
4379
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
4380
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
4381
|
+
* `optimized_url_promise` to `null`.
|
|
4382
|
+
*/
|
|
4383
|
+
uploadViaStorage(file: File | Blob, uploadOptions?: {
|
|
4384
|
+
userId?: string;
|
|
4385
|
+
filename?: string;
|
|
4386
|
+
metadata?: Record<string, unknown>;
|
|
4387
|
+
onProgress?: (progress: number) => void;
|
|
4388
|
+
signal?: AbortSignal;
|
|
4389
|
+
}, requestOptions?: RequestOptions): Promise<ApiResponse<UploadViaStorageResult>>;
|
|
4390
|
+
/**
|
|
4391
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
4392
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
4393
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
4394
|
+
* which uses the on-demand transform path).
|
|
4395
|
+
*/
|
|
4396
|
+
private pollOptimizationComplete;
|
|
4314
4397
|
/** @deprecated Use upload() instead */
|
|
4315
4398
|
uploadPhoto(file: File | Blob, options?: {
|
|
4316
4399
|
metadata?: Record<string, unknown>;
|
package/dist/index.js
CHANGED
|
@@ -2335,6 +2335,40 @@ var StorageService = class extends ServiceModule {
|
|
|
2335
2335
|
return { data: null, error: { code: "upload_error", message, status: 0 } };
|
|
2336
2336
|
}
|
|
2337
2337
|
}
|
|
2338
|
+
/**
|
|
2339
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
2340
|
+
*
|
|
2341
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
2342
|
+
* - `is_public: false` — caller cannot opt out
|
|
2343
|
+
* - no client-side compression — preserve the original bytes
|
|
2344
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
2345
|
+
*
|
|
2346
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
2347
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
2348
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
2349
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
2350
|
+
*
|
|
2351
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
2352
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
2353
|
+
*/
|
|
2354
|
+
async uploadPrivate(file, options) {
|
|
2355
|
+
const result = await this.upload(file, {
|
|
2356
|
+
...options,
|
|
2357
|
+
isPublic: false,
|
|
2358
|
+
skipCompression: true
|
|
2359
|
+
});
|
|
2360
|
+
if (result.data && result.data.is_public === true) {
|
|
2361
|
+
return {
|
|
2362
|
+
data: null,
|
|
2363
|
+
error: {
|
|
2364
|
+
code: "visibility_violation",
|
|
2365
|
+
message: "Storage returned is_public=true for an uploadPrivate() call. This usually indicates a server-side bug or an admin override; the caller asked for a private upload.",
|
|
2366
|
+
status: 0
|
|
2367
|
+
}
|
|
2368
|
+
};
|
|
2369
|
+
}
|
|
2370
|
+
return result;
|
|
2371
|
+
}
|
|
2338
2372
|
// --------------------------------------------------------------------------
|
|
2339
2373
|
// Direct Upload (3-step with retry + stall)
|
|
2340
2374
|
// --------------------------------------------------------------------------
|
|
@@ -6042,8 +6076,14 @@ var SearchService = class extends ServiceModule {
|
|
|
6042
6076
|
// src/services/photo.ts
|
|
6043
6077
|
var PHOTO_BREAKPOINTS = [36, 150, 320, 640, 1080];
|
|
6044
6078
|
var PhotoService = class extends ServiceModule {
|
|
6045
|
-
|
|
6046
|
-
|
|
6079
|
+
/**
|
|
6080
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
6081
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
6082
|
+
* instantiate `PhotoService` directly.
|
|
6083
|
+
*/
|
|
6084
|
+
constructor(client, storage) {
|
|
6085
|
+
super(client);
|
|
6086
|
+
this.storage = storage;
|
|
6047
6087
|
this.basePath = "/v1/photos";
|
|
6048
6088
|
}
|
|
6049
6089
|
async upload(file, uploadOptions, requestOptions) {
|
|
@@ -6183,6 +6223,87 @@ var PhotoService = class extends ServiceModule {
|
|
|
6183
6223
|
}
|
|
6184
6224
|
};
|
|
6185
6225
|
}
|
|
6226
|
+
/**
|
|
6227
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
6228
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
6229
|
+
*
|
|
6230
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
6231
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
6232
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
6233
|
+
* usable URLs.
|
|
6234
|
+
*
|
|
6235
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
6236
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
6237
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
6238
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
6239
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
6240
|
+
* subscription.
|
|
6241
|
+
*
|
|
6242
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
6243
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
6244
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
6245
|
+
* `optimized_url_promise` to `null`.
|
|
6246
|
+
*/
|
|
6247
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
6248
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
6249
|
+
filename: uploadOptions?.filename,
|
|
6250
|
+
metadata: uploadOptions?.metadata,
|
|
6251
|
+
onProgress: uploadOptions?.onProgress,
|
|
6252
|
+
signal: uploadOptions?.signal
|
|
6253
|
+
});
|
|
6254
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
6255
|
+
return { data: null, error: uploadResult.error };
|
|
6256
|
+
}
|
|
6257
|
+
const fileInfo = uploadResult.data;
|
|
6258
|
+
const fileId = fileInfo.id;
|
|
6259
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
6260
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
6261
|
+
if (registerResult.error || !registerResult.data) {
|
|
6262
|
+
console.warn(
|
|
6263
|
+
"[scalemule-sdk] photo.register() failed after storage upload; optimized variants unavailable.",
|
|
6264
|
+
registerResult.error
|
|
6265
|
+
);
|
|
6266
|
+
return {
|
|
6267
|
+
data: {
|
|
6268
|
+
file_id: fileId,
|
|
6269
|
+
photo_id: null,
|
|
6270
|
+
original_view_url: originalViewUrl,
|
|
6271
|
+
optimized_url_promise: Promise.resolve(null)
|
|
6272
|
+
},
|
|
6273
|
+
error: null
|
|
6274
|
+
};
|
|
6275
|
+
}
|
|
6276
|
+
const photoId = registerResult.data.id;
|
|
6277
|
+
const optimizedUrlPromise = this.pollOptimizationComplete(photoId, requestOptions);
|
|
6278
|
+
return {
|
|
6279
|
+
data: {
|
|
6280
|
+
file_id: fileId,
|
|
6281
|
+
photo_id: photoId,
|
|
6282
|
+
original_view_url: originalViewUrl,
|
|
6283
|
+
optimized_url_promise: optimizedUrlPromise
|
|
6284
|
+
},
|
|
6285
|
+
error: null
|
|
6286
|
+
};
|
|
6287
|
+
}
|
|
6288
|
+
/**
|
|
6289
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
6290
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
6291
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
6292
|
+
* which uses the on-demand transform path).
|
|
6293
|
+
*/
|
|
6294
|
+
async pollOptimizationComplete(photoId, requestOptions) {
|
|
6295
|
+
const intervalMs = 250;
|
|
6296
|
+
const maxAttempts = 40;
|
|
6297
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
6298
|
+
const result = await this.get(photoId, requestOptions);
|
|
6299
|
+
const status = result.data?.optimization_status;
|
|
6300
|
+
if (status === "completed") {
|
|
6301
|
+
return this.getOptimalUrl(photoId, 1080);
|
|
6302
|
+
}
|
|
6303
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
6304
|
+
}
|
|
6305
|
+
return null;
|
|
6306
|
+
}
|
|
6186
6307
|
/** @deprecated Use upload() instead */
|
|
6187
6308
|
async uploadPhoto(file, options) {
|
|
6188
6309
|
return this.upload(file, options);
|
|
@@ -7046,7 +7167,7 @@ var ScaleMule = class {
|
|
|
7046
7167
|
this.events = new EventsService(this._client);
|
|
7047
7168
|
this.graph = new GraphService(this._client);
|
|
7048
7169
|
this.functions = new FunctionsService(this._client);
|
|
7049
|
-
this.photo = new PhotoService(this._client);
|
|
7170
|
+
this.photo = new PhotoService(this._client, this.storage);
|
|
7050
7171
|
this.flagContent = new FlagContentService(this._client);
|
|
7051
7172
|
this.creatorMaker = new CreatorMakerService(this._client);
|
|
7052
7173
|
this.compliance = new ComplianceService(this._client);
|
package/dist/index.mjs
CHANGED
|
@@ -1966,6 +1966,40 @@ var StorageService = class extends ServiceModule {
|
|
|
1966
1966
|
return { data: null, error: { code: "upload_error", message, status: 0 } };
|
|
1967
1967
|
}
|
|
1968
1968
|
}
|
|
1969
|
+
/**
|
|
1970
|
+
* Upload a file as a private attachment (e.g. chat / DM attachment).
|
|
1971
|
+
*
|
|
1972
|
+
* Same browser→S3 pipeline as {@link upload}, but enforces:
|
|
1973
|
+
* - `is_public: false` — caller cannot opt out
|
|
1974
|
+
* - no client-side compression — preserve the original bytes
|
|
1975
|
+
* - fail-closed if storage returns `is_public: true` for any reason
|
|
1976
|
+
*
|
|
1977
|
+
* The shared primitive used by `@scalemule/chat`'s chat-attachment uploader
|
|
1978
|
+
* and by `@scalemule/nextjs`'s `useMedia()` when an app's media policy is
|
|
1979
|
+
* `fast_trusted`. Both packages call this method via `@scalemule/sdk` —
|
|
1980
|
+
* `@scalemule/nextjs` does not depend on `@scalemule/chat`.
|
|
1981
|
+
*
|
|
1982
|
+
* See ADR-2026-04-26 (realtime-chat media pipeline) and
|
|
1983
|
+
* docs/MEDIA-UPLOADS.md for the full pattern.
|
|
1984
|
+
*/
|
|
1985
|
+
async uploadPrivate(file, options) {
|
|
1986
|
+
const result = await this.upload(file, {
|
|
1987
|
+
...options,
|
|
1988
|
+
isPublic: false,
|
|
1989
|
+
skipCompression: true
|
|
1990
|
+
});
|
|
1991
|
+
if (result.data && result.data.is_public === true) {
|
|
1992
|
+
return {
|
|
1993
|
+
data: null,
|
|
1994
|
+
error: {
|
|
1995
|
+
code: "visibility_violation",
|
|
1996
|
+
message: "Storage returned is_public=true for an uploadPrivate() call. This usually indicates a server-side bug or an admin override; the caller asked for a private upload.",
|
|
1997
|
+
status: 0
|
|
1998
|
+
}
|
|
1999
|
+
};
|
|
2000
|
+
}
|
|
2001
|
+
return result;
|
|
2002
|
+
}
|
|
1969
2003
|
// --------------------------------------------------------------------------
|
|
1970
2004
|
// Direct Upload (3-step with retry + stall)
|
|
1971
2005
|
// --------------------------------------------------------------------------
|
|
@@ -5670,8 +5704,14 @@ var SearchService = class extends ServiceModule {
|
|
|
5670
5704
|
// src/services/photo.ts
|
|
5671
5705
|
var PHOTO_BREAKPOINTS = [36, 150, 320, 640, 1080];
|
|
5672
5706
|
var PhotoService = class extends ServiceModule {
|
|
5673
|
-
|
|
5674
|
-
|
|
5707
|
+
/**
|
|
5708
|
+
* @param storage Required for {@link uploadViaStorage}. Wired up by the
|
|
5709
|
+
* top-level {@link ScaleMule} constructor — most call sites should not
|
|
5710
|
+
* instantiate `PhotoService` directly.
|
|
5711
|
+
*/
|
|
5712
|
+
constructor(client, storage) {
|
|
5713
|
+
super(client);
|
|
5714
|
+
this.storage = storage;
|
|
5675
5715
|
this.basePath = "/v1/photos";
|
|
5676
5716
|
}
|
|
5677
5717
|
async upload(file, uploadOptions, requestOptions) {
|
|
@@ -5811,6 +5851,87 @@ var PhotoService = class extends ServiceModule {
|
|
|
5811
5851
|
}
|
|
5812
5852
|
};
|
|
5813
5853
|
}
|
|
5854
|
+
/**
|
|
5855
|
+
* Upload a file to storage (browser → S3 direct, private, uncompressed) and
|
|
5856
|
+
* register it with the photo service so optimization + transform URLs work.
|
|
5857
|
+
*
|
|
5858
|
+
* The canonical chat-attachment / progressive-image upload primitive. Same
|
|
5859
|
+
* presigned-direct-to-S3 path as `storage.uploadPrivate()`, plus a follow-up
|
|
5860
|
+
* `photo.register()` call so `getTransformUrl()` / `getOptimalUrl()` return
|
|
5861
|
+
* usable URLs.
|
|
5862
|
+
*
|
|
5863
|
+
* The returned `optimized_url_promise` resolves once the photo's
|
|
5864
|
+
* `optimization_status` flips to `completed` (or once a 10s timeout fires;
|
|
5865
|
+
* the caller can still use `getTransformUrl()` directly — the on-demand
|
|
5866
|
+
* transform path produces a variant even before pre-rendered breakpoints
|
|
5867
|
+
* are cached). Phase 3 of ADR-2026-04-26 replaces the poll with a realtime
|
|
5868
|
+
* subscription.
|
|
5869
|
+
*
|
|
5870
|
+
* If `register()` fails after a successful storage upload (e.g. scan times
|
|
5871
|
+
* out), the file is *not* lost: the returned `file_id` is still valid as a
|
|
5872
|
+
* generic storage file. The SDK logs a warning and resolves
|
|
5873
|
+
* `optimized_url_promise` to `null`.
|
|
5874
|
+
*/
|
|
5875
|
+
async uploadViaStorage(file, uploadOptions, requestOptions) {
|
|
5876
|
+
const uploadResult = await this.storage.uploadPrivate(file, {
|
|
5877
|
+
filename: uploadOptions?.filename,
|
|
5878
|
+
metadata: uploadOptions?.metadata,
|
|
5879
|
+
onProgress: uploadOptions?.onProgress,
|
|
5880
|
+
signal: uploadOptions?.signal
|
|
5881
|
+
});
|
|
5882
|
+
if (uploadResult.error || !uploadResult.data) {
|
|
5883
|
+
return { data: null, error: uploadResult.error };
|
|
5884
|
+
}
|
|
5885
|
+
const fileInfo = uploadResult.data;
|
|
5886
|
+
const fileId = fileInfo.id;
|
|
5887
|
+
const originalViewUrl = fileInfo.url ?? null;
|
|
5888
|
+
const registerResult = await this.register({ fileId, userId: uploadOptions?.userId }, requestOptions);
|
|
5889
|
+
if (registerResult.error || !registerResult.data) {
|
|
5890
|
+
console.warn(
|
|
5891
|
+
"[scalemule-sdk] photo.register() failed after storage upload; optimized variants unavailable.",
|
|
5892
|
+
registerResult.error
|
|
5893
|
+
);
|
|
5894
|
+
return {
|
|
5895
|
+
data: {
|
|
5896
|
+
file_id: fileId,
|
|
5897
|
+
photo_id: null,
|
|
5898
|
+
original_view_url: originalViewUrl,
|
|
5899
|
+
optimized_url_promise: Promise.resolve(null)
|
|
5900
|
+
},
|
|
5901
|
+
error: null
|
|
5902
|
+
};
|
|
5903
|
+
}
|
|
5904
|
+
const photoId = registerResult.data.id;
|
|
5905
|
+
const optimizedUrlPromise = this.pollOptimizationComplete(photoId, requestOptions);
|
|
5906
|
+
return {
|
|
5907
|
+
data: {
|
|
5908
|
+
file_id: fileId,
|
|
5909
|
+
photo_id: photoId,
|
|
5910
|
+
original_view_url: originalViewUrl,
|
|
5911
|
+
optimized_url_promise: optimizedUrlPromise
|
|
5912
|
+
},
|
|
5913
|
+
error: null
|
|
5914
|
+
};
|
|
5915
|
+
}
|
|
5916
|
+
/**
|
|
5917
|
+
* Poll {@link get} until the photo's `optimization_status` is `completed`
|
|
5918
|
+
* or the 10s timeout fires. Resolves to a usable transform URL on success;
|
|
5919
|
+
* `null` on timeout (caller should fall back to {@link getTransformUrl}
|
|
5920
|
+
* which uses the on-demand transform path).
|
|
5921
|
+
*/
|
|
5922
|
+
async pollOptimizationComplete(photoId, requestOptions) {
|
|
5923
|
+
const intervalMs = 250;
|
|
5924
|
+
const maxAttempts = 40;
|
|
5925
|
+
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
5926
|
+
const result = await this.get(photoId, requestOptions);
|
|
5927
|
+
const status = result.data?.optimization_status;
|
|
5928
|
+
if (status === "completed") {
|
|
5929
|
+
return this.getOptimalUrl(photoId, 1080);
|
|
5930
|
+
}
|
|
5931
|
+
await new Promise((r) => setTimeout(r, intervalMs));
|
|
5932
|
+
}
|
|
5933
|
+
return null;
|
|
5934
|
+
}
|
|
5814
5935
|
/** @deprecated Use upload() instead */
|
|
5815
5936
|
async uploadPhoto(file, options) {
|
|
5816
5937
|
return this.upload(file, options);
|
|
@@ -6674,7 +6795,7 @@ var ScaleMule = class {
|
|
|
6674
6795
|
this.events = new EventsService(this._client);
|
|
6675
6796
|
this.graph = new GraphService(this._client);
|
|
6676
6797
|
this.functions = new FunctionsService(this._client);
|
|
6677
|
-
this.photo = new PhotoService(this._client);
|
|
6798
|
+
this.photo = new PhotoService(this._client, this.storage);
|
|
6678
6799
|
this.flagContent = new FlagContentService(this._client);
|
|
6679
6800
|
this.creatorMaker = new CreatorMakerService(this._client);
|
|
6680
6801
|
this.compliance = new ComplianceService(this._client);
|