@scalemule/sdk 0.0.15 → 0.0.18

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.mjs CHANGED
@@ -1497,6 +1497,22 @@ var StorageService = class extends ServiceModule {
1497
1497
  file_id,
1498
1498
  reason: uploadResult.error.code
1499
1499
  });
1500
+ await this.reportUploadFailureBestEffort(
1501
+ {
1502
+ fileId: file_id,
1503
+ completionToken: completion_token,
1504
+ step: "s3_put",
1505
+ errorCode: uploadResult.error.code,
1506
+ errorMessage: uploadResult.error.message,
1507
+ httpStatus: uploadResult.error.status || void 0,
1508
+ attempt: asNumber2(uploadResult.error.details?.attempt),
1509
+ diagnostics: {
1510
+ ...getUploadEnvironmentDiagnostics(),
1511
+ ...uploadResult.error.details || {}
1512
+ }
1513
+ },
1514
+ requestOpts
1515
+ );
1500
1516
  return { data: null, error: uploadResult.error };
1501
1517
  }
1502
1518
  const completeResult = await this.post(
@@ -1514,6 +1530,21 @@ var StorageService = class extends ServiceModule {
1514
1530
  file_id,
1515
1531
  duration_ms: Date.now() - directStart
1516
1532
  });
1533
+ await this.reportUploadFailureBestEffort(
1534
+ {
1535
+ fileId: file_id,
1536
+ completionToken: completion_token,
1537
+ step: "complete",
1538
+ errorCode: completeResult.error.code,
1539
+ errorMessage: completeResult.error.message,
1540
+ httpStatus: completeResult.error.status || void 0,
1541
+ diagnostics: {
1542
+ ...getUploadEnvironmentDiagnostics(),
1543
+ duration_ms: Date.now() - directStart
1544
+ }
1545
+ },
1546
+ requestOpts
1547
+ );
1517
1548
  } else {
1518
1549
  telemetry?.emit(sessionId, "upload.completed", {
1519
1550
  file_id,
@@ -1676,6 +1707,17 @@ var StorageService = class extends ServiceModule {
1676
1707
  if (options?.signal?.aborted) {
1677
1708
  await this.abortMultipart(upload_session_id, completionToken, requestOpts);
1678
1709
  telemetry?.emit(sessionId, "upload.aborted", { file_id });
1710
+ await this.reportUploadFailureBestEffort(
1711
+ {
1712
+ fileId: file_id,
1713
+ completionToken,
1714
+ step: "multipart_abort",
1715
+ errorCode: "aborted",
1716
+ errorMessage: "Upload aborted",
1717
+ diagnostics: getUploadEnvironmentDiagnostics()
1718
+ },
1719
+ requestOpts
1720
+ );
1679
1721
  return { data: null, error: { code: "aborted", message: "Upload aborted", status: 0 } };
1680
1722
  }
1681
1723
  const remainingUrlCount = pendingParts.slice(partIndex).filter((p) => availableUrls.has(p)).length;
@@ -1777,6 +1819,20 @@ var StorageService = class extends ServiceModule {
1777
1819
  const errorMsg = result.error || "Part upload returned no ETag";
1778
1820
  await this.abortMultipart(upload_session_id, completionToken, requestOpts);
1779
1821
  telemetry?.emit(sessionId, "upload.multipart.aborted", { file_id, error: errorMsg });
1822
+ await this.reportUploadFailureBestEffort(
1823
+ {
1824
+ fileId: file_id,
1825
+ completionToken,
1826
+ step: "multipart_part",
1827
+ errorCode: "upload_error",
1828
+ errorMessage: errorMsg,
1829
+ diagnostics: {
1830
+ ...getUploadEnvironmentDiagnostics(),
1831
+ part_number: result.partNum
1832
+ }
1833
+ },
1834
+ requestOpts
1835
+ );
1780
1836
  return {
1781
1837
  data: null,
1782
1838
  error: { code: "upload_error", message: `Part ${result.partNum} failed: ${errorMsg}`, status: 0 }
@@ -1816,6 +1872,21 @@ var StorageService = class extends ServiceModule {
1816
1872
  error: completeResult.error.message,
1817
1873
  duration_ms: Date.now() - multipartStart
1818
1874
  });
1875
+ await this.reportUploadFailureBestEffort(
1876
+ {
1877
+ fileId: file_id,
1878
+ completionToken,
1879
+ step: "multipart_complete",
1880
+ errorCode: completeResult.error.code,
1881
+ errorMessage: completeResult.error.message,
1882
+ httpStatus: completeResult.error.status || void 0,
1883
+ diagnostics: {
1884
+ ...getUploadEnvironmentDiagnostics(),
1885
+ duration_ms: Date.now() - multipartStart
1886
+ }
1887
+ },
1888
+ requestOpts
1889
+ );
1819
1890
  return { data: null, error: completeResult.error };
1820
1891
  }
1821
1892
  telemetry?.emit(sessionId, "upload.multipart.completed", {
@@ -1876,6 +1947,7 @@ var StorageService = class extends ServiceModule {
1876
1947
  content_type: contentType,
1877
1948
  is_public: options?.isPublic ?? true,
1878
1949
  expires_in: options?.expiresIn ?? 3600,
1950
+ size_bytes: options?.sizeBytes,
1879
1951
  metadata: options?.metadata
1880
1952
  },
1881
1953
  requestOptions
@@ -1897,6 +1969,26 @@ var StorageService = class extends ServiceModule {
1897
1969
  requestOptions
1898
1970
  );
1899
1971
  }
1972
+ /**
1973
+ * Persist a structured client-side upload failure against a file record.
1974
+ * Best used by split-upload clients that call getUploadUrl() manually.
1975
+ */
1976
+ async reportUploadFailure(params, requestOptions) {
1977
+ return this.post(
1978
+ "/signed-url/report-failure",
1979
+ {
1980
+ file_id: params.fileId,
1981
+ completion_token: params.completionToken,
1982
+ step: params.step,
1983
+ error_code: params.errorCode,
1984
+ error_message: params.errorMessage,
1985
+ http_status: params.httpStatus,
1986
+ attempt: params.attempt,
1987
+ diagnostics: params.diagnostics
1988
+ },
1989
+ requestOptions
1990
+ );
1991
+ }
1900
1992
  // --------------------------------------------------------------------------
1901
1993
  // Multipart Public API (for advanced/server-side usage)
1902
1994
  // --------------------------------------------------------------------------
@@ -2022,6 +2114,13 @@ var StorageService = class extends ServiceModule {
2022
2114
  telemetry?.emit(sessionId || "", "upload.retried", { attempt });
2023
2115
  }
2024
2116
  const result = await this.uploadToPresignedUrl(url, file, onProgress, signal);
2117
+ if (result.error) {
2118
+ result.error.details = {
2119
+ ...result.error.details || {},
2120
+ attempt: attempt + 1,
2121
+ max_attempts: RETRY_DELAYS.length
2122
+ };
2123
+ }
2025
2124
  if (!result.error) return result;
2026
2125
  if (result.error.code === "aborted") return result;
2027
2126
  if (result.error.status && NON_RETRYABLE_STATUS_CODES.has(result.error.status)) {
@@ -2073,7 +2172,12 @@ var StorageService = class extends ServiceModule {
2073
2172
  error: {
2074
2173
  code: "upload_error",
2075
2174
  message: `S3 upload failed: ${response.status} ${response.statusText}`,
2076
- status: response.status
2175
+ status: response.status,
2176
+ details: {
2177
+ transport: "fetch",
2178
+ total_bytes: file.size,
2179
+ online: getOnlineStatus()
2180
+ }
2077
2181
  }
2078
2182
  };
2079
2183
  }
@@ -2091,7 +2195,12 @@ var StorageService = class extends ServiceModule {
2091
2195
  error: {
2092
2196
  code: isStall ? "upload_stalled" : "upload_error",
2093
2197
  message: isStall ? `Upload stalled (no progress for ${stallTimeout / 1e3}s)` : err instanceof Error ? err.message : "S3 upload failed",
2094
- status: 0
2198
+ status: 0,
2199
+ details: {
2200
+ transport: "fetch",
2201
+ total_bytes: file.size,
2202
+ online: getOnlineStatus()
2203
+ }
2095
2204
  }
2096
2205
  };
2097
2206
  }
@@ -2101,6 +2210,8 @@ var StorageService = class extends ServiceModule {
2101
2210
  const xhr = new XMLHttpRequest();
2102
2211
  const stallTimeout = getStallTimeout();
2103
2212
  let stallTimer = null;
2213
+ let lastLoaded = 0;
2214
+ let totalBytes = file.size;
2104
2215
  const resetStallTimer = () => {
2105
2216
  if (stallTimer !== null) clearTimeout(stallTimer);
2106
2217
  stallTimer = setTimeout(() => {
@@ -2110,7 +2221,14 @@ var StorageService = class extends ServiceModule {
2110
2221
  error: {
2111
2222
  code: "upload_stalled",
2112
2223
  message: `Upload stalled (no progress for ${stallTimeout / 1e3}s)`,
2113
- status: 0
2224
+ status: 0,
2225
+ details: {
2226
+ transport: "xhr",
2227
+ bytes_sent: lastLoaded,
2228
+ total_bytes: totalBytes,
2229
+ progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
2230
+ online: getOnlineStatus()
2231
+ }
2114
2232
  }
2115
2233
  });
2116
2234
  }, stallTimeout);
@@ -2137,6 +2255,8 @@ var StorageService = class extends ServiceModule {
2137
2255
  }
2138
2256
  xhr.upload.addEventListener("progress", (event) => {
2139
2257
  resetStallTimer();
2258
+ lastLoaded = event.loaded;
2259
+ totalBytes = event.total || totalBytes;
2140
2260
  if (event.lengthComputable && onProgress) {
2141
2261
  onProgress(Math.round(event.loaded / event.total * 100));
2142
2262
  }
@@ -2152,7 +2272,14 @@ var StorageService = class extends ServiceModule {
2152
2272
  error: {
2153
2273
  code: "upload_error",
2154
2274
  message: `S3 upload failed: ${xhr.status}`,
2155
- status: xhr.status
2275
+ status: xhr.status,
2276
+ details: {
2277
+ transport: "xhr",
2278
+ bytes_sent: lastLoaded,
2279
+ total_bytes: totalBytes,
2280
+ progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
2281
+ online: getOnlineStatus()
2282
+ }
2156
2283
  }
2157
2284
  });
2158
2285
  }
@@ -2161,7 +2288,18 @@ var StorageService = class extends ServiceModule {
2161
2288
  clearStallTimer();
2162
2289
  resolve({
2163
2290
  data: null,
2164
- error: { code: "upload_error", message: "S3 upload failed", status: 0 }
2291
+ error: {
2292
+ code: "upload_error",
2293
+ message: "S3 upload failed",
2294
+ status: 0,
2295
+ details: {
2296
+ transport: "xhr",
2297
+ bytes_sent: lastLoaded,
2298
+ total_bytes: totalBytes,
2299
+ progress_percent: totalBytes > 0 ? Math.round(lastLoaded / totalBytes * 100) : void 0,
2300
+ online: getOnlineStatus()
2301
+ }
2302
+ }
2165
2303
  });
2166
2304
  });
2167
2305
  xhr.addEventListener("abort", () => {
@@ -2270,6 +2408,12 @@ var StorageService = class extends ServiceModule {
2270
2408
  return null;
2271
2409
  }
2272
2410
  }
2411
+ async reportUploadFailureBestEffort(params, requestOptions) {
2412
+ try {
2413
+ await this.reportUploadFailure(params, requestOptions);
2414
+ } catch {
2415
+ }
2416
+ }
2273
2417
  getOrCreateTelemetry() {
2274
2418
  if (!this.telemetry) {
2275
2419
  this.telemetry = new UploadTelemetry(this.client);
@@ -2309,6 +2453,38 @@ function getNetworkEffectiveType() {
2309
2453
  }
2310
2454
  return "4g";
2311
2455
  }
2456
+ function getOnlineStatus() {
2457
+ if (typeof navigator === "undefined") return void 0;
2458
+ return navigator.onLine;
2459
+ }
2460
+ function getUploadEnvironmentDiagnostics() {
2461
+ const diagnostics = {
2462
+ network_type: getNetworkEffectiveType(),
2463
+ online: getOnlineStatus()
2464
+ };
2465
+ if (typeof navigator !== "undefined") {
2466
+ const nav = navigator;
2467
+ if (typeof nav.hardwareConcurrency === "number") {
2468
+ diagnostics.hardware_concurrency = nav.hardwareConcurrency;
2469
+ }
2470
+ if (typeof nav.deviceMemory === "number") {
2471
+ diagnostics.device_memory_gb = nav.deviceMemory;
2472
+ }
2473
+ if (nav.connection?.downlink != null) {
2474
+ diagnostics.downlink_mbps = nav.connection.downlink;
2475
+ }
2476
+ if (nav.connection?.rtt != null) {
2477
+ diagnostics.rtt_ms = nav.connection.rtt;
2478
+ }
2479
+ }
2480
+ if (typeof document !== "undefined") {
2481
+ diagnostics.visibility_state = document.visibilityState;
2482
+ }
2483
+ return diagnostics;
2484
+ }
2485
+ function asNumber2(value) {
2486
+ return typeof value === "number" && Number.isFinite(value) ? value : void 0;
2487
+ }
2312
2488
 
2313
2489
  // src/services/upload-strategy.ts
2314
2490
  var MULTIPART_THRESHOLD2 = 8 * 1024 * 1024;
@@ -2404,6 +2580,199 @@ function getPartRange(partNumber, chunkSize, totalSize) {
2404
2580
  return { start, end, size: end - start };
2405
2581
  }
2406
2582
 
2583
+ // src/services/upload-to-s3.ts
2584
+ var DEFAULT_RETRY_DELAYS = [0, 1e3, 3e3];
2585
+ var DEFAULT_STALL_TIMEOUT_MS3 = 45e3;
2586
+ var DEFAULT_CONCURRENCY = 3;
2587
+ async function uploadSingleToS3(url, file, options) {
2588
+ const maxRetries = options?.maxRetries ?? 3;
2589
+ const retryDelays = DEFAULT_RETRY_DELAYS.slice(0, maxRetries);
2590
+ const stallTimeout = options?.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS3;
2591
+ for (let attempt = 0; attempt < retryDelays.length; attempt++) {
2592
+ if (attempt > 0) {
2593
+ await sleep3(retryDelays[attempt] || 1e3);
2594
+ }
2595
+ if (options?.signal?.aborted) {
2596
+ return { success: false, error: "Upload aborted" };
2597
+ }
2598
+ const result = await doSinglePut(url, file, options?.onProgress, options?.signal, stallTimeout);
2599
+ if (result === "success") return { success: true };
2600
+ if (result === "abort") return { success: false, error: "Upload aborted" };
2601
+ if (result === "stall") return { success: false, error: "Upload stalled \u2014 no progress" };
2602
+ }
2603
+ return { success: false, error: "Upload failed after retries" };
2604
+ }
2605
+ function doSinglePut(url, file, onProgress, signal, stallTimeoutMs) {
2606
+ return new Promise((resolve) => {
2607
+ const xhr = new XMLHttpRequest();
2608
+ let stallTimer = null;
2609
+ const resetStallTimer = () => {
2610
+ if (stallTimer) clearTimeout(stallTimer);
2611
+ if (stallTimeoutMs) {
2612
+ stallTimer = setTimeout(() => {
2613
+ xhr.abort();
2614
+ resolve("stall");
2615
+ }, stallTimeoutMs);
2616
+ }
2617
+ };
2618
+ xhr.upload.addEventListener("progress", (e) => {
2619
+ resetStallTimer();
2620
+ if (e.lengthComputable && onProgress) {
2621
+ onProgress({
2622
+ loaded: e.loaded,
2623
+ total: e.total,
2624
+ percentage: Math.round(e.loaded / e.total * 100)
2625
+ });
2626
+ }
2627
+ });
2628
+ xhr.addEventListener("load", () => {
2629
+ if (stallTimer) clearTimeout(stallTimer);
2630
+ if (xhr.status >= 200 && xhr.status < 300) {
2631
+ resolve("success");
2632
+ } else if (xhr.status >= 500) {
2633
+ resolve("retry");
2634
+ } else {
2635
+ resolve("retry");
2636
+ }
2637
+ });
2638
+ xhr.addEventListener("error", () => {
2639
+ if (stallTimer) clearTimeout(stallTimer);
2640
+ resolve("retry");
2641
+ });
2642
+ xhr.addEventListener("abort", () => {
2643
+ if (stallTimer) clearTimeout(stallTimer);
2644
+ });
2645
+ if (signal) {
2646
+ signal.addEventListener(
2647
+ "abort",
2648
+ () => {
2649
+ xhr.abort();
2650
+ if (stallTimer) clearTimeout(stallTimer);
2651
+ resolve("abort");
2652
+ },
2653
+ { once: true }
2654
+ );
2655
+ }
2656
+ xhr.open("PUT", url);
2657
+ xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
2658
+ resetStallTimer();
2659
+ xhr.send(file);
2660
+ });
2661
+ }
2662
+ async function uploadMultipartToS3(file, config, options) {
2663
+ const { partSizeBytes, totalParts, partUrls: initialPartUrls, fetchMoreUrls } = config;
2664
+ const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
2665
+ const maxRetries = options?.maxRetries ?? 3;
2666
+ const completedParts = [];
2667
+ const availableUrls = /* @__PURE__ */ new Map();
2668
+ for (const pu of initialPartUrls) {
2669
+ availableUrls.set(pu.partNumber, pu.url);
2670
+ }
2671
+ let totalUploaded = 0;
2672
+ for (let i = 0; i < totalParts; i += concurrency) {
2673
+ if (options?.signal?.aborted) {
2674
+ return { success: false, error: "Upload aborted" };
2675
+ }
2676
+ const batchPartNumbers = [];
2677
+ for (let j = i; j < Math.min(i + concurrency, totalParts); j++) {
2678
+ batchPartNumbers.push(j + 1);
2679
+ }
2680
+ const missingUrls = batchPartNumbers.filter((p) => !availableUrls.has(p));
2681
+ if (missingUrls.length > 0 && fetchMoreUrls) {
2682
+ const fetched = await fetchMoreUrls(missingUrls);
2683
+ if (fetched) {
2684
+ for (const pu of fetched) availableUrls.set(pu.partNumber, pu.url);
2685
+ }
2686
+ }
2687
+ const results = await Promise.all(
2688
+ batchPartNumbers.map(async (partNum) => {
2689
+ const url = availableUrls.get(partNum);
2690
+ if (!url) return { partNum, error: "No URL available" };
2691
+ const start = (partNum - 1) * partSizeBytes;
2692
+ const end = Math.min(start + partSizeBytes, file.size);
2693
+ const blob = file.slice(start, end);
2694
+ let result = await uploadPartWithRetry(url, blob, partNum, maxRetries, options?.signal);
2695
+ if (!result && fetchMoreUrls) {
2696
+ const freshUrls = await fetchMoreUrls([partNum]);
2697
+ if (freshUrls?.[0]) {
2698
+ availableUrls.set(partNum, freshUrls[0].url);
2699
+ result = await uploadPartWithRetry(freshUrls[0].url, blob, partNum, maxRetries, options?.signal);
2700
+ }
2701
+ }
2702
+ if (result) {
2703
+ totalUploaded += end - start;
2704
+ options?.onProgress?.({
2705
+ loaded: totalUploaded,
2706
+ total: file.size,
2707
+ percentage: Math.round(totalUploaded / file.size * 100)
2708
+ });
2709
+ return { partNum, etag: result.etag };
2710
+ }
2711
+ return { partNum, error: "Part upload failed after retries" };
2712
+ })
2713
+ );
2714
+ for (const result of results) {
2715
+ if ("error" in result) {
2716
+ return { success: false, error: `Part ${result.partNum}: ${result.error}` };
2717
+ }
2718
+ completedParts.push({ partNumber: result.partNum, etag: result.etag });
2719
+ }
2720
+ }
2721
+ return {
2722
+ success: true,
2723
+ parts: completedParts.sort((a, b) => a.partNumber - b.partNumber)
2724
+ };
2725
+ }
2726
+ async function uploadPartWithRetry(url, blob, _partNumber, maxRetries, signal) {
2727
+ const retryDelays = DEFAULT_RETRY_DELAYS.slice(0, maxRetries);
2728
+ for (let attempt = 0; attempt < retryDelays.length; attempt++) {
2729
+ if (attempt > 0) await sleep3(retryDelays[attempt] || 1e3);
2730
+ if (signal?.aborted) return null;
2731
+ const result = await doPartPut(url, blob, signal);
2732
+ if (result === "abort") return null;
2733
+ if (typeof result === "object") return result;
2734
+ }
2735
+ return null;
2736
+ }
2737
+ function doPartPut(url, blob, signal) {
2738
+ return new Promise((resolve) => {
2739
+ const xhr = new XMLHttpRequest();
2740
+ xhr.addEventListener("load", () => {
2741
+ if (xhr.status >= 200 && xhr.status < 300) {
2742
+ const etag = xhr.getResponseHeader("etag");
2743
+ if (etag) {
2744
+ resolve({ etag });
2745
+ } else {
2746
+ resolve("retry");
2747
+ }
2748
+ } else if (xhr.status === 403) {
2749
+ resolve("retry");
2750
+ } else if (xhr.status >= 500) {
2751
+ resolve("retry");
2752
+ } else {
2753
+ resolve("retry");
2754
+ }
2755
+ });
2756
+ xhr.addEventListener("error", () => resolve("retry"));
2757
+ xhr.addEventListener("abort", () => resolve("abort"));
2758
+ if (signal) {
2759
+ signal.addEventListener(
2760
+ "abort",
2761
+ () => {
2762
+ xhr.abort();
2763
+ resolve("abort");
2764
+ },
2765
+ { once: true }
2766
+ );
2767
+ }
2768
+ xhr.open("PUT", url);
2769
+ xhr.send(blob);
2770
+ });
2771
+ }
2772
+ function sleep3(ms) {
2773
+ return new Promise((r) => setTimeout(r, ms));
2774
+ }
2775
+
2407
2776
  // src/services/realtime.ts
2408
2777
  var DEFAULT_RECONNECT_BASE_MS = 1e3;
2409
2778
  var MAX_RECONNECT_MS = 3e4;
@@ -4065,8 +4434,8 @@ var SearchService = class extends ServiceModule {
4065
4434
  async query(queryStr, queryOptions, requestOptions) {
4066
4435
  return this.post("", { query: queryStr, ...queryOptions }, requestOptions);
4067
4436
  }
4068
- async index(indexName, document, options) {
4069
- return this.post("/documents", { index: indexName, ...document }, options);
4437
+ async index(indexName, document2, options) {
4438
+ return this.post("/documents", { index: indexName, ...document2 }, options);
4070
4439
  }
4071
4440
  async removeDocument(indexName, docId, options) {
4072
4441
  return this.del(`/documents/${indexName}/${docId}`, options);
@@ -5095,5 +5464,7 @@ export {
5095
5464
  normalizeAndValidatePhone,
5096
5465
  normalizePhoneNumber,
5097
5466
  resolveStrategy,
5467
+ uploadMultipartToS3,
5468
+ uploadSingleToS3,
5098
5469
  validateIP
5099
5470
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.15",
3
+ "version": "0.0.18",
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",