@scalemule/sdk 0.0.50 → 0.0.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1628,9 +1628,17 @@ interface S3SingleUploadOptions {
1628
1628
  /** Stall timeout in ms — abort if no progress for this long (default: 45000) */
1629
1629
  stallTimeoutMs?: number;
1630
1630
  }
1631
+ /** Structured failure code emitted by uploadSingleToS3 / uploadMultipartToS3. */
1632
+ type S3UploadErrorCode = 's3_signature_error' | 's3_client_error' | 's3_server_error' | 's3_transient_error' | 's3_missing_etag' | 'network_error' | 'stalled' | 'aborted' | 'aborted_unexpected';
1631
1633
  interface S3SingleUploadResult {
1632
1634
  success: boolean;
1633
1635
  error?: string;
1636
+ /** S3 HTTP status (when failure originated from S3) */
1637
+ status?: number;
1638
+ /** Structured failure code — see S3UploadErrorCode for the full enum. */
1639
+ code?: S3UploadErrorCode;
1640
+ /** Truncated S3 response body — invaluable for diagnosing SignatureDoesNotMatch vs RequestTimeout etc. */
1641
+ s3ErrorBody?: string;
1634
1642
  }
1635
1643
  interface MultipartPartUrl {
1636
1644
  partNumber: number;
@@ -1661,6 +1669,10 @@ interface S3MultipartResult {
1661
1669
  success: boolean;
1662
1670
  parts?: PartResult[];
1663
1671
  error?: string;
1672
+ status?: number;
1673
+ /** Structured failure code — see S3UploadErrorCode for the full enum. */
1674
+ code?: S3UploadErrorCode;
1675
+ s3ErrorBody?: string;
1664
1676
  }
1665
1677
  /**
1666
1678
  * Upload a file to S3 via a single presigned PUT.
package/dist/index.d.ts CHANGED
@@ -1628,9 +1628,17 @@ interface S3SingleUploadOptions {
1628
1628
  /** Stall timeout in ms — abort if no progress for this long (default: 45000) */
1629
1629
  stallTimeoutMs?: number;
1630
1630
  }
1631
+ /** Structured failure code emitted by uploadSingleToS3 / uploadMultipartToS3. */
1632
+ type S3UploadErrorCode = 's3_signature_error' | 's3_client_error' | 's3_server_error' | 's3_transient_error' | 's3_missing_etag' | 'network_error' | 'stalled' | 'aborted' | 'aborted_unexpected';
1631
1633
  interface S3SingleUploadResult {
1632
1634
  success: boolean;
1633
1635
  error?: string;
1636
+ /** S3 HTTP status (when failure originated from S3) */
1637
+ status?: number;
1638
+ /** Structured failure code — see S3UploadErrorCode for the full enum. */
1639
+ code?: S3UploadErrorCode;
1640
+ /** Truncated S3 response body — invaluable for diagnosing SignatureDoesNotMatch vs RequestTimeout etc. */
1641
+ s3ErrorBody?: string;
1634
1642
  }
1635
1643
  interface MultipartPartUrl {
1636
1644
  partNumber: number;
@@ -1661,6 +1669,10 @@ interface S3MultipartResult {
1661
1669
  success: boolean;
1662
1670
  parts?: PartResult[];
1663
1671
  error?: string;
1672
+ status?: number;
1673
+ /** Structured failure code — see S3UploadErrorCode for the full enum. */
1674
+ code?: S3UploadErrorCode;
1675
+ s3ErrorBody?: string;
1664
1676
  }
1665
1677
  /**
1666
1678
  * Upload a file to S3 via a single presigned PUT.
package/dist/index.js CHANGED
@@ -3195,6 +3195,7 @@ var StorageService = class extends ServiceModule {
3195
3195
  clearTimeout(timer);
3196
3196
  parentSignalCleanup?.();
3197
3197
  if (!response.ok) {
3198
+ const s3ErrorBody = await response.text().catch(() => "");
3198
3199
  return {
3199
3200
  data: null,
3200
3201
  error: {
@@ -3204,7 +3205,9 @@ var StorageService = class extends ServiceModule {
3204
3205
  details: {
3205
3206
  transport: "fetch",
3206
3207
  total_bytes: file.size,
3207
- online: getOnlineStatus()
3208
+ online: getOnlineStatus(),
3209
+ s3_error_body: s3ErrorBody.slice(0, 1024),
3210
+ s3_error_code: extractS3ErrorCode(s3ErrorBody)
3208
3211
  }
3209
3212
  }
3210
3213
  };
@@ -3295,6 +3298,7 @@ var StorageService = class extends ServiceModule {
3295
3298
  onProgress?.(100);
3296
3299
  resolve({ data: null, error: null });
3297
3300
  } else {
3301
+ const body = (xhr.responseText || "").slice(0, 1024);
3298
3302
  resolve({
3299
3303
  data: null,
3300
3304
  error: {
@@ -3306,7 +3310,9 @@ var StorageService = class extends ServiceModule {
3306
3310
  bytes_sent: lastLoaded,
3307
3311
  total_bytes: totalBytes,
3308
3312
  progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
3309
- online: getOnlineStatus()
3313
+ online: getOnlineStatus(),
3314
+ s3_error_body: body,
3315
+ s3_error_code: extractS3ErrorCode(body)
3310
3316
  }
3311
3317
  }
3312
3318
  });
@@ -3385,12 +3391,18 @@ var StorageService = class extends ServiceModule {
3385
3391
  }
3386
3392
  return { etag };
3387
3393
  }
3394
+ const body = await response.text().catch(() => "");
3395
+ const s3ErrorCode = extractS3ErrorCode(body);
3388
3396
  if (NON_RETRYABLE_STATUS_CODES.has(response.status)) {
3389
- return { error: `Part upload failed: ${response.status}`, status: response.status, code: "s3_error" };
3397
+ return {
3398
+ error: `Part upload failed: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
3399
+ status: response.status,
3400
+ code: response.status === 403 ? "s3_signature_error" : "s3_error"
3401
+ };
3390
3402
  }
3391
3403
  if (attempt === RETRY_DELAYS.length - 1) {
3392
3404
  return {
3393
- error: `Part upload failed after retries: ${response.status}`,
3405
+ error: `Part upload failed after retries: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
3394
3406
  status: response.status,
3395
3407
  code: "s3_error"
3396
3408
  };
@@ -3516,6 +3528,11 @@ function getUploadEnvironmentDiagnostics() {
3516
3528
  function asNumber2(value) {
3517
3529
  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
3518
3530
  }
3531
+ function extractS3ErrorCode(body) {
3532
+ if (!body) return void 0;
3533
+ const m = body.match(/<Code>([^<]+)<\/Code>/);
3534
+ return m ? m[1] : void 0;
3535
+ }
3519
3536
 
3520
3537
  // src/index.ts
3521
3538
  init_upload_resume();
@@ -3618,33 +3635,65 @@ function getPartRange(partNumber, chunkSize, totalSize) {
3618
3635
  var DEFAULT_RETRY_DELAYS = [0, 1e3, 3e3];
3619
3636
  var DEFAULT_STALL_TIMEOUT_MS3 = 45e3;
3620
3637
  var DEFAULT_CONCURRENCY = 3;
3638
+ var FATAL_S3_STATUS = /* @__PURE__ */ new Set([400, 403, 404, 411, 412, 413, 415]);
3639
+ var MAX_ERROR_BODY_BYTES = 1024;
3621
3640
  async function uploadSingleToS3(url, file, options) {
3622
3641
  const maxRetries = options?.maxRetries ?? 3;
3623
3642
  const retryDelays = DEFAULT_RETRY_DELAYS.slice(0, maxRetries);
3624
3643
  const stallTimeout = options?.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS3;
3644
+ let lastFailure = null;
3625
3645
  for (let attempt = 0; attempt < retryDelays.length; attempt++) {
3626
3646
  if (attempt > 0) {
3627
3647
  await sleep3(retryDelays[attempt] || 1e3);
3628
3648
  }
3629
3649
  if (options?.signal?.aborted) {
3630
- return { success: false, error: "Upload aborted" };
3650
+ return { success: false, error: "Upload aborted", code: "aborted" };
3631
3651
  }
3632
3652
  const result = await doSinglePut(url, file, options?.onProgress, options?.signal, stallTimeout);
3633
- if (result === "success") return { success: true };
3634
- if (result === "abort") return { success: false, error: "Upload aborted" };
3653
+ if (result.kind === "success") return { success: true };
3654
+ if (result.kind === "abort") return { success: false, error: "Upload aborted", code: "aborted" };
3655
+ lastFailure = result;
3656
+ if (result.kind === "fatal") {
3657
+ return {
3658
+ success: false,
3659
+ error: `S3 rejected upload: ${result.status} ${result.code}`,
3660
+ status: result.status,
3661
+ code: result.code,
3662
+ s3ErrorBody: result.body
3663
+ };
3664
+ }
3635
3665
  }
3636
- return { success: false, error: "Upload failed after retries" };
3666
+ return {
3667
+ success: false,
3668
+ error: lastFailure?.kind === "stall" ? "Upload stalled after retries" : "Upload failed after retries",
3669
+ status: lastFailure && "status" in lastFailure ? lastFailure.status : void 0,
3670
+ code: lastFailure?.kind === "stall" ? "stalled" : lastFailure && "code" in lastFailure ? lastFailure.code : "network_error",
3671
+ s3ErrorBody: lastFailure && "body" in lastFailure ? lastFailure.body : void 0
3672
+ };
3673
+ }
3674
+ function classifyS3Status(status) {
3675
+ if (status === 403) return { fatal: true, code: "s3_signature_error" };
3676
+ if (FATAL_S3_STATUS.has(status)) return { fatal: true, code: "s3_client_error" };
3677
+ if (status >= 500) return { fatal: false, code: "s3_server_error" };
3678
+ return { fatal: false, code: "s3_transient_error" };
3637
3679
  }
3638
3680
  function doSinglePut(url, file, onProgress, signal, stallTimeoutMs) {
3639
3681
  return new Promise((resolve) => {
3640
3682
  const xhr = new XMLHttpRequest();
3641
3683
  let stallTimer = null;
3684
+ let resolved = false;
3685
+ const settle = (r) => {
3686
+ if (resolved) return;
3687
+ resolved = true;
3688
+ if (stallTimer) clearTimeout(stallTimer);
3689
+ resolve(r);
3690
+ };
3642
3691
  const resetStallTimer = () => {
3643
3692
  if (stallTimer) clearTimeout(stallTimer);
3644
3693
  if (stallTimeoutMs) {
3645
3694
  stallTimer = setTimeout(() => {
3646
3695
  xhr.abort();
3647
- resolve("stall");
3696
+ settle({ kind: "stall" });
3648
3697
  }, stallTimeoutMs);
3649
3698
  }
3650
3699
  };
@@ -3659,29 +3708,27 @@ function doSinglePut(url, file, onProgress, signal, stallTimeoutMs) {
3659
3708
  }
3660
3709
  });
3661
3710
  xhr.addEventListener("load", () => {
3662
- if (stallTimer) clearTimeout(stallTimer);
3663
3711
  if (xhr.status >= 200 && xhr.status < 300) {
3664
- resolve("success");
3665
- } else if (xhr.status >= 500) {
3666
- resolve("retry");
3667
- } else {
3668
- resolve("retry");
3712
+ settle({ kind: "success" });
3713
+ return;
3669
3714
  }
3715
+ const body = (xhr.responseText || "").slice(0, MAX_ERROR_BODY_BYTES);
3716
+ const { fatal, code } = classifyS3Status(xhr.status);
3717
+ settle({ kind: fatal ? "fatal" : "retry", status: xhr.status, code, body });
3670
3718
  });
3671
- xhr.addEventListener("error", () => {
3672
- if (stallTimer) clearTimeout(stallTimer);
3673
- resolve("retry");
3674
- });
3719
+ xhr.addEventListener("error", () => settle({ kind: "retry", code: "network_error" }));
3675
3720
  xhr.addEventListener("abort", () => {
3676
- if (stallTimer) clearTimeout(stallTimer);
3721
+ if (!resolved) settle({ kind: "retry", code: "aborted_unexpected" });
3677
3722
  });
3678
3723
  if (signal) {
3679
3724
  signal.addEventListener(
3680
3725
  "abort",
3681
3726
  () => {
3682
- xhr.abort();
3683
- if (stallTimer) clearTimeout(stallTimer);
3684
- resolve("abort");
3727
+ try {
3728
+ xhr.abort();
3729
+ } catch {
3730
+ }
3731
+ settle({ kind: "abort" });
3685
3732
  },
3686
3733
  { once: true }
3687
3734
  );
@@ -3726,7 +3773,7 @@ async function uploadMultipartToS3(file, config, options) {
3726
3773
  const end = Math.min(start + partSizeBytes, file.size);
3727
3774
  const blob = file.slice(start, end);
3728
3775
  let result = await uploadPartWithRetry(url, blob, partNum, maxRetries, options?.signal, stallTimeoutMs);
3729
- if (!result && fetchMoreUrls) {
3776
+ if ("error" in result && fetchMoreUrls && (result.code === "s3_signature_error" || result.refreshable)) {
3730
3777
  const freshUrls = await fetchMoreUrls([partNum]);
3731
3778
  if (freshUrls?.[0]) {
3732
3779
  availableUrls.set(partNum, freshUrls[0].url);
@@ -3740,7 +3787,7 @@ async function uploadMultipartToS3(file, config, options) {
3740
3787
  );
3741
3788
  }
3742
3789
  }
3743
- if (result) {
3790
+ if ("etag" in result) {
3744
3791
  totalUploaded += end - start;
3745
3792
  options?.onProgress?.({
3746
3793
  loaded: totalUploaded,
@@ -3749,12 +3796,25 @@ async function uploadMultipartToS3(file, config, options) {
3749
3796
  });
3750
3797
  return { partNum, etag: result.etag };
3751
3798
  }
3752
- return { partNum, error: "Part upload failed after retries" };
3799
+ return {
3800
+ partNum,
3801
+ error: result.error,
3802
+ status: result.status,
3803
+ code: result.code,
3804
+ body: result.body
3805
+ };
3753
3806
  })
3754
3807
  );
3755
3808
  for (const result of results) {
3756
3809
  if ("error" in result) {
3757
- return { success: false, error: `Part ${result.partNum}: ${result.error}` };
3810
+ const detail = result.status ? ` (HTTP ${result.status} ${result.code ?? ""})` : "";
3811
+ return {
3812
+ success: false,
3813
+ error: `Part ${result.partNum}: ${result.error}${detail}`,
3814
+ status: result.status,
3815
+ code: result.code,
3816
+ s3ErrorBody: result.body
3817
+ };
3758
3818
  }
3759
3819
  completedParts.push({ partNumber: result.partNum, etag: result.etag });
3760
3820
  }
@@ -3766,14 +3826,36 @@ async function uploadMultipartToS3(file, config, options) {
3766
3826
  }
3767
3827
  async function uploadPartWithRetry(url, blob, _partNumber, maxRetries, signal, stallTimeoutMs) {
3768
3828
  const retryDelays = DEFAULT_RETRY_DELAYS.slice(0, maxRetries);
3829
+ let lastFailure = {
3830
+ error: "Part upload failed",
3831
+ code: "network_error",
3832
+ refreshable: false
3833
+ };
3769
3834
  for (let attempt = 0; attempt < retryDelays.length; attempt++) {
3770
3835
  if (attempt > 0) await sleep3(retryDelays[attempt] || 1e3);
3771
- if (signal?.aborted) return null;
3836
+ if (signal?.aborted) {
3837
+ return { error: "Upload aborted", code: "aborted", refreshable: false };
3838
+ }
3772
3839
  const result = await doPartPut(url, blob, signal, stallTimeoutMs);
3773
- if (result === "abort") return null;
3774
- if (typeof result === "object") return result;
3840
+ if (result.kind === "success") return { etag: result.etag };
3841
+ if (result.kind === "abort") {
3842
+ return { error: "Upload aborted", code: "aborted", refreshable: false };
3843
+ }
3844
+ if (result.kind === "stall") {
3845
+ lastFailure = { error: "Part stalled", code: "stalled", refreshable: false };
3846
+ continue;
3847
+ }
3848
+ lastFailure = {
3849
+ error: `Part HTTP ${result.status ?? "network"}`,
3850
+ status: result.status,
3851
+ code: result.code ?? "network_error",
3852
+ body: result.body,
3853
+ refreshable: !!result.refreshable
3854
+ };
3855
+ if (result.refreshable) return lastFailure;
3856
+ if (result.kind === "fatal") return lastFailure;
3775
3857
  }
3776
- return null;
3858
+ return { ...lastFailure, error: `Part upload failed after retries: ${lastFailure.error}` };
3777
3859
  }
3778
3860
  function doPartPut(url, blob, signal, stallTimeoutMs) {
3779
3861
  return new Promise((resolve) => {
@@ -3791,39 +3873,50 @@ function doPartPut(url, blob, signal, stallTimeoutMs) {
3791
3873
  if (stallTimeoutMs) {
3792
3874
  stallTimer = setTimeout(() => {
3793
3875
  xhr.abort();
3794
- settle("retry");
3876
+ settle({ kind: "stall" });
3795
3877
  }, stallTimeoutMs);
3796
3878
  }
3797
3879
  };
3798
- xhr.upload.addEventListener("progress", () => {
3799
- resetStallTimer();
3800
- });
3880
+ xhr.upload.addEventListener("progress", () => resetStallTimer());
3801
3881
  xhr.addEventListener("load", () => {
3802
3882
  if (xhr.status >= 200 && xhr.status < 300) {
3803
3883
  const etag = xhr.getResponseHeader("etag");
3804
3884
  if (etag) {
3805
- settle({ etag });
3885
+ settle({ kind: "success", etag });
3806
3886
  } else {
3807
- settle("retry");
3887
+ settle({
3888
+ kind: "retry",
3889
+ status: xhr.status,
3890
+ code: "s3_missing_etag",
3891
+ body: (xhr.responseText || "").slice(0, MAX_ERROR_BODY_BYTES)
3892
+ });
3808
3893
  }
3809
- } else if (xhr.status === 403) {
3810
- settle("retry");
3811
- } else if (xhr.status >= 500) {
3812
- settle("retry");
3813
- } else {
3814
- settle("retry");
3894
+ return;
3815
3895
  }
3896
+ const body = (xhr.responseText || "").slice(0, MAX_ERROR_BODY_BYTES);
3897
+ const { fatal, code } = classifyS3Status(xhr.status);
3898
+ const refreshable = xhr.status === 403;
3899
+ settle({
3900
+ kind: refreshable ? "retry" : fatal ? "fatal" : "retry",
3901
+ status: xhr.status,
3902
+ code,
3903
+ body,
3904
+ refreshable
3905
+ });
3816
3906
  });
3817
- xhr.addEventListener("error", () => settle("retry"));
3907
+ xhr.addEventListener("error", () => settle({ kind: "retry", code: "network_error" }));
3818
3908
  xhr.addEventListener("abort", () => {
3819
- if (!resolved) settle("abort");
3909
+ if (!resolved) settle({ kind: "abort" });
3820
3910
  });
3821
3911
  if (signal) {
3822
3912
  signal.addEventListener(
3823
3913
  "abort",
3824
3914
  () => {
3825
- xhr.abort();
3826
- settle("abort");
3915
+ try {
3916
+ xhr.abort();
3917
+ } catch {
3918
+ }
3919
+ settle({ kind: "abort" });
3827
3920
  },
3828
3921
  { once: true }
3829
3922
  );
package/dist/index.mjs CHANGED
@@ -2824,6 +2824,7 @@ var StorageService = class extends ServiceModule {
2824
2824
  clearTimeout(timer);
2825
2825
  parentSignalCleanup?.();
2826
2826
  if (!response.ok) {
2827
+ const s3ErrorBody = await response.text().catch(() => "");
2827
2828
  return {
2828
2829
  data: null,
2829
2830
  error: {
@@ -2833,7 +2834,9 @@ var StorageService = class extends ServiceModule {
2833
2834
  details: {
2834
2835
  transport: "fetch",
2835
2836
  total_bytes: file.size,
2836
- online: getOnlineStatus()
2837
+ online: getOnlineStatus(),
2838
+ s3_error_body: s3ErrorBody.slice(0, 1024),
2839
+ s3_error_code: extractS3ErrorCode(s3ErrorBody)
2837
2840
  }
2838
2841
  }
2839
2842
  };
@@ -2924,6 +2927,7 @@ var StorageService = class extends ServiceModule {
2924
2927
  onProgress?.(100);
2925
2928
  resolve({ data: null, error: null });
2926
2929
  } else {
2930
+ const body = (xhr.responseText || "").slice(0, 1024);
2927
2931
  resolve({
2928
2932
  data: null,
2929
2933
  error: {
@@ -2935,7 +2939,9 @@ var StorageService = class extends ServiceModule {
2935
2939
  bytes_sent: lastLoaded,
2936
2940
  total_bytes: totalBytes,
2937
2941
  progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
2938
- online: getOnlineStatus()
2942
+ online: getOnlineStatus(),
2943
+ s3_error_body: body,
2944
+ s3_error_code: extractS3ErrorCode(body)
2939
2945
  }
2940
2946
  }
2941
2947
  });
@@ -3014,12 +3020,18 @@ var StorageService = class extends ServiceModule {
3014
3020
  }
3015
3021
  return { etag };
3016
3022
  }
3023
+ const body = await response.text().catch(() => "");
3024
+ const s3ErrorCode = extractS3ErrorCode(body);
3017
3025
  if (NON_RETRYABLE_STATUS_CODES.has(response.status)) {
3018
- return { error: `Part upload failed: ${response.status}`, status: response.status, code: "s3_error" };
3026
+ return {
3027
+ error: `Part upload failed: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
3028
+ status: response.status,
3029
+ code: response.status === 403 ? "s3_signature_error" : "s3_error"
3030
+ };
3019
3031
  }
3020
3032
  if (attempt === RETRY_DELAYS.length - 1) {
3021
3033
  return {
3022
- error: `Part upload failed after retries: ${response.status}`,
3034
+ error: `Part upload failed after retries: ${response.status}${s3ErrorCode ? ` (${s3ErrorCode})` : ""}`,
3023
3035
  status: response.status,
3024
3036
  code: "s3_error"
3025
3037
  };
@@ -3145,6 +3157,11 @@ function getUploadEnvironmentDiagnostics() {
3145
3157
  function asNumber2(value) {
3146
3158
  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
3147
3159
  }
3160
+ function extractS3ErrorCode(body) {
3161
+ if (!body) return void 0;
3162
+ const m = body.match(/<Code>([^<]+)<\/Code>/);
3163
+ return m ? m[1] : void 0;
3164
+ }
3148
3165
 
3149
3166
  // src/services/upload-strategy.ts
3150
3167
  var MULTIPART_THRESHOLD2 = 8 * 1024 * 1024;
@@ -3244,33 +3261,65 @@ function getPartRange(partNumber, chunkSize, totalSize) {
3244
3261
  var DEFAULT_RETRY_DELAYS = [0, 1e3, 3e3];
3245
3262
  var DEFAULT_STALL_TIMEOUT_MS3 = 45e3;
3246
3263
  var DEFAULT_CONCURRENCY = 3;
3264
+ var FATAL_S3_STATUS = /* @__PURE__ */ new Set([400, 403, 404, 411, 412, 413, 415]);
3265
+ var MAX_ERROR_BODY_BYTES = 1024;
3247
3266
  async function uploadSingleToS3(url, file, options) {
3248
3267
  const maxRetries = options?.maxRetries ?? 3;
3249
3268
  const retryDelays = DEFAULT_RETRY_DELAYS.slice(0, maxRetries);
3250
3269
  const stallTimeout = options?.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS3;
3270
+ let lastFailure = null;
3251
3271
  for (let attempt = 0; attempt < retryDelays.length; attempt++) {
3252
3272
  if (attempt > 0) {
3253
3273
  await sleep3(retryDelays[attempt] || 1e3);
3254
3274
  }
3255
3275
  if (options?.signal?.aborted) {
3256
- return { success: false, error: "Upload aborted" };
3276
+ return { success: false, error: "Upload aborted", code: "aborted" };
3257
3277
  }
3258
3278
  const result = await doSinglePut(url, file, options?.onProgress, options?.signal, stallTimeout);
3259
- if (result === "success") return { success: true };
3260
- if (result === "abort") return { success: false, error: "Upload aborted" };
3279
+ if (result.kind === "success") return { success: true };
3280
+ if (result.kind === "abort") return { success: false, error: "Upload aborted", code: "aborted" };
3281
+ lastFailure = result;
3282
+ if (result.kind === "fatal") {
3283
+ return {
3284
+ success: false,
3285
+ error: `S3 rejected upload: ${result.status} ${result.code}`,
3286
+ status: result.status,
3287
+ code: result.code,
3288
+ s3ErrorBody: result.body
3289
+ };
3290
+ }
3261
3291
  }
3262
- return { success: false, error: "Upload failed after retries" };
3292
+ return {
3293
+ success: false,
3294
+ error: lastFailure?.kind === "stall" ? "Upload stalled after retries" : "Upload failed after retries",
3295
+ status: lastFailure && "status" in lastFailure ? lastFailure.status : void 0,
3296
+ code: lastFailure?.kind === "stall" ? "stalled" : lastFailure && "code" in lastFailure ? lastFailure.code : "network_error",
3297
+ s3ErrorBody: lastFailure && "body" in lastFailure ? lastFailure.body : void 0
3298
+ };
3299
+ }
3300
+ function classifyS3Status(status) {
3301
+ if (status === 403) return { fatal: true, code: "s3_signature_error" };
3302
+ if (FATAL_S3_STATUS.has(status)) return { fatal: true, code: "s3_client_error" };
3303
+ if (status >= 500) return { fatal: false, code: "s3_server_error" };
3304
+ return { fatal: false, code: "s3_transient_error" };
3263
3305
  }
3264
3306
  function doSinglePut(url, file, onProgress, signal, stallTimeoutMs) {
3265
3307
  return new Promise((resolve) => {
3266
3308
  const xhr = new XMLHttpRequest();
3267
3309
  let stallTimer = null;
3310
+ let resolved = false;
3311
+ const settle = (r) => {
3312
+ if (resolved) return;
3313
+ resolved = true;
3314
+ if (stallTimer) clearTimeout(stallTimer);
3315
+ resolve(r);
3316
+ };
3268
3317
  const resetStallTimer = () => {
3269
3318
  if (stallTimer) clearTimeout(stallTimer);
3270
3319
  if (stallTimeoutMs) {
3271
3320
  stallTimer = setTimeout(() => {
3272
3321
  xhr.abort();
3273
- resolve("stall");
3322
+ settle({ kind: "stall" });
3274
3323
  }, stallTimeoutMs);
3275
3324
  }
3276
3325
  };
@@ -3285,29 +3334,27 @@ function doSinglePut(url, file, onProgress, signal, stallTimeoutMs) {
3285
3334
  }
3286
3335
  });
3287
3336
  xhr.addEventListener("load", () => {
3288
- if (stallTimer) clearTimeout(stallTimer);
3289
3337
  if (xhr.status >= 200 && xhr.status < 300) {
3290
- resolve("success");
3291
- } else if (xhr.status >= 500) {
3292
- resolve("retry");
3293
- } else {
3294
- resolve("retry");
3338
+ settle({ kind: "success" });
3339
+ return;
3295
3340
  }
3341
+ const body = (xhr.responseText || "").slice(0, MAX_ERROR_BODY_BYTES);
3342
+ const { fatal, code } = classifyS3Status(xhr.status);
3343
+ settle({ kind: fatal ? "fatal" : "retry", status: xhr.status, code, body });
3296
3344
  });
3297
- xhr.addEventListener("error", () => {
3298
- if (stallTimer) clearTimeout(stallTimer);
3299
- resolve("retry");
3300
- });
3345
+ xhr.addEventListener("error", () => settle({ kind: "retry", code: "network_error" }));
3301
3346
  xhr.addEventListener("abort", () => {
3302
- if (stallTimer) clearTimeout(stallTimer);
3347
+ if (!resolved) settle({ kind: "retry", code: "aborted_unexpected" });
3303
3348
  });
3304
3349
  if (signal) {
3305
3350
  signal.addEventListener(
3306
3351
  "abort",
3307
3352
  () => {
3308
- xhr.abort();
3309
- if (stallTimer) clearTimeout(stallTimer);
3310
- resolve("abort");
3353
+ try {
3354
+ xhr.abort();
3355
+ } catch {
3356
+ }
3357
+ settle({ kind: "abort" });
3311
3358
  },
3312
3359
  { once: true }
3313
3360
  );
@@ -3352,7 +3399,7 @@ async function uploadMultipartToS3(file, config, options) {
3352
3399
  const end = Math.min(start + partSizeBytes, file.size);
3353
3400
  const blob = file.slice(start, end);
3354
3401
  let result = await uploadPartWithRetry(url, blob, partNum, maxRetries, options?.signal, stallTimeoutMs);
3355
- if (!result && fetchMoreUrls) {
3402
+ if ("error" in result && fetchMoreUrls && (result.code === "s3_signature_error" || result.refreshable)) {
3356
3403
  const freshUrls = await fetchMoreUrls([partNum]);
3357
3404
  if (freshUrls?.[0]) {
3358
3405
  availableUrls.set(partNum, freshUrls[0].url);
@@ -3366,7 +3413,7 @@ async function uploadMultipartToS3(file, config, options) {
3366
3413
  );
3367
3414
  }
3368
3415
  }
3369
- if (result) {
3416
+ if ("etag" in result) {
3370
3417
  totalUploaded += end - start;
3371
3418
  options?.onProgress?.({
3372
3419
  loaded: totalUploaded,
@@ -3375,12 +3422,25 @@ async function uploadMultipartToS3(file, config, options) {
3375
3422
  });
3376
3423
  return { partNum, etag: result.etag };
3377
3424
  }
3378
- return { partNum, error: "Part upload failed after retries" };
3425
+ return {
3426
+ partNum,
3427
+ error: result.error,
3428
+ status: result.status,
3429
+ code: result.code,
3430
+ body: result.body
3431
+ };
3379
3432
  })
3380
3433
  );
3381
3434
  for (const result of results) {
3382
3435
  if ("error" in result) {
3383
- return { success: false, error: `Part ${result.partNum}: ${result.error}` };
3436
+ const detail = result.status ? ` (HTTP ${result.status} ${result.code ?? ""})` : "";
3437
+ return {
3438
+ success: false,
3439
+ error: `Part ${result.partNum}: ${result.error}${detail}`,
3440
+ status: result.status,
3441
+ code: result.code,
3442
+ s3ErrorBody: result.body
3443
+ };
3384
3444
  }
3385
3445
  completedParts.push({ partNumber: result.partNum, etag: result.etag });
3386
3446
  }
@@ -3392,14 +3452,36 @@ async function uploadMultipartToS3(file, config, options) {
3392
3452
  }
3393
3453
  async function uploadPartWithRetry(url, blob, _partNumber, maxRetries, signal, stallTimeoutMs) {
3394
3454
  const retryDelays = DEFAULT_RETRY_DELAYS.slice(0, maxRetries);
3455
+ let lastFailure = {
3456
+ error: "Part upload failed",
3457
+ code: "network_error",
3458
+ refreshable: false
3459
+ };
3395
3460
  for (let attempt = 0; attempt < retryDelays.length; attempt++) {
3396
3461
  if (attempt > 0) await sleep3(retryDelays[attempt] || 1e3);
3397
- if (signal?.aborted) return null;
3462
+ if (signal?.aborted) {
3463
+ return { error: "Upload aborted", code: "aborted", refreshable: false };
3464
+ }
3398
3465
  const result = await doPartPut(url, blob, signal, stallTimeoutMs);
3399
- if (result === "abort") return null;
3400
- if (typeof result === "object") return result;
3466
+ if (result.kind === "success") return { etag: result.etag };
3467
+ if (result.kind === "abort") {
3468
+ return { error: "Upload aborted", code: "aborted", refreshable: false };
3469
+ }
3470
+ if (result.kind === "stall") {
3471
+ lastFailure = { error: "Part stalled", code: "stalled", refreshable: false };
3472
+ continue;
3473
+ }
3474
+ lastFailure = {
3475
+ error: `Part HTTP ${result.status ?? "network"}`,
3476
+ status: result.status,
3477
+ code: result.code ?? "network_error",
3478
+ body: result.body,
3479
+ refreshable: !!result.refreshable
3480
+ };
3481
+ if (result.refreshable) return lastFailure;
3482
+ if (result.kind === "fatal") return lastFailure;
3401
3483
  }
3402
- return null;
3484
+ return { ...lastFailure, error: `Part upload failed after retries: ${lastFailure.error}` };
3403
3485
  }
3404
3486
  function doPartPut(url, blob, signal, stallTimeoutMs) {
3405
3487
  return new Promise((resolve) => {
@@ -3417,39 +3499,50 @@ function doPartPut(url, blob, signal, stallTimeoutMs) {
3417
3499
  if (stallTimeoutMs) {
3418
3500
  stallTimer = setTimeout(() => {
3419
3501
  xhr.abort();
3420
- settle("retry");
3502
+ settle({ kind: "stall" });
3421
3503
  }, stallTimeoutMs);
3422
3504
  }
3423
3505
  };
3424
- xhr.upload.addEventListener("progress", () => {
3425
- resetStallTimer();
3426
- });
3506
+ xhr.upload.addEventListener("progress", () => resetStallTimer());
3427
3507
  xhr.addEventListener("load", () => {
3428
3508
  if (xhr.status >= 200 && xhr.status < 300) {
3429
3509
  const etag = xhr.getResponseHeader("etag");
3430
3510
  if (etag) {
3431
- settle({ etag });
3511
+ settle({ kind: "success", etag });
3432
3512
  } else {
3433
- settle("retry");
3513
+ settle({
3514
+ kind: "retry",
3515
+ status: xhr.status,
3516
+ code: "s3_missing_etag",
3517
+ body: (xhr.responseText || "").slice(0, MAX_ERROR_BODY_BYTES)
3518
+ });
3434
3519
  }
3435
- } else if (xhr.status === 403) {
3436
- settle("retry");
3437
- } else if (xhr.status >= 500) {
3438
- settle("retry");
3439
- } else {
3440
- settle("retry");
3520
+ return;
3441
3521
  }
3522
+ const body = (xhr.responseText || "").slice(0, MAX_ERROR_BODY_BYTES);
3523
+ const { fatal, code } = classifyS3Status(xhr.status);
3524
+ const refreshable = xhr.status === 403;
3525
+ settle({
3526
+ kind: refreshable ? "retry" : fatal ? "fatal" : "retry",
3527
+ status: xhr.status,
3528
+ code,
3529
+ body,
3530
+ refreshable
3531
+ });
3442
3532
  });
3443
- xhr.addEventListener("error", () => settle("retry"));
3533
+ xhr.addEventListener("error", () => settle({ kind: "retry", code: "network_error" }));
3444
3534
  xhr.addEventListener("abort", () => {
3445
- if (!resolved) settle("abort");
3535
+ if (!resolved) settle({ kind: "abort" });
3446
3536
  });
3447
3537
  if (signal) {
3448
3538
  signal.addEventListener(
3449
3539
  "abort",
3450
3540
  () => {
3451
- xhr.abort();
3452
- settle("abort");
3541
+ try {
3542
+ xhr.abort();
3543
+ } catch {
3544
+ }
3545
+ settle({ kind: "abort" });
3453
3546
  },
3454
3547
  { once: true }
3455
3548
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.50",
3
+ "version": "0.0.51",
4
4
  "description": "Official TypeScript/JavaScript SDK for ScaleMule Backend-as-a-Service",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",