deepline 0.1.317 → 0.1.318

package/dist/bundling-sources/sdk/src/client.ts

@@ -1127,6 +1127,13 @@ function isStagedUploadMintUnsupported(error: unknown): boolean {
   return error instanceof DeeplineError && error.statusCode === 404;
 }
 
+function isStagedUploadDirectEgressDenied(error: unknown): boolean {
+  return (
+    error instanceof DeeplineError &&
+    error.code === 'STAGED_FILE_UPLOAD_EGRESS_DENIED'
+  );
+}
+
 function formatMegabytes(bytes: number): string {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
@@ -1159,10 +1166,16 @@ async function uploadStagedFileToPresignedUrl(input: {
         return;
       }
       const text = await response.text().catch(() => '');
+      const egressDenied =
+        response.status === 403 &&
+        response.headers.get('x-deny-reason')?.trim().toLowerCase() ===
+          'host_not_allowed';
       lastError = new DeeplineError(
         `Direct storage upload of ${input.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
         response.status,
-        'STAGED_FILE_UPLOAD_FAILED',
+        egressDenied
+          ? 'STAGED_FILE_UPLOAD_EGRESS_DENIED'
+          : 'STAGED_FILE_UPLOAD_FAILED',
         { logicalPath: input.logicalPath },
       );
       // 4xx (other than throttling) will not recover on retry.
@@ -2502,7 +2515,10 @@ export class DeeplineClient {
       );
     }
 
-    await Promise.all(
+    type DirectStageResult =
+      | { ref: PlayStagedFileRef }
+      | { fallbackFile: (typeof files)[number] };
+    const directResults: DirectStageResult[] = await Promise.all(
       files.map(async (file) => {
         const upload = uploadByIdentity.get(
           stagedUploadIdentity(file.logicalPath, file.contentHash),
@@ -2515,32 +2531,46 @@ export class DeeplineClient {
           );
         }
         if (upload.alreadyStaged || !upload.uploadUrl) {
-          return;
+          return { ref: upload.ref };
+        }
+        try {
+          await uploadStagedFileToPresignedUrl({
+            url: upload.uploadUrl,
+            headers: upload.uploadHeaders ?? {
+              'content-type': file.contentType,
+            },
+            body: decodeBase64Bytes(file.contentBase64),
+            logicalPath: file.logicalPath,
+          });
+          return { ref: upload.ref };
+        } catch (error) {
+          if (isStagedUploadDirectEgressDenied(error)) {
+            return { fallbackFile: file };
+          }
+          throw error;
         }
-        await uploadStagedFileToPresignedUrl({
-          url: upload.uploadUrl,
-          headers: upload.uploadHeaders ?? {
-            'content-type': file.contentType,
-          },
-          body: decodeBase64Bytes(file.contentBase64),
-          logicalPath: file.logicalPath,
-        });
       }),
     );
 
-    return files.map((file) => {
-      const upload = uploadByIdentity.get(
-        stagedUploadIdentity(file.logicalPath, file.contentHash),
-      );
-      if (!upload) {
-        throw new DeeplineError(
-          `The staging server did not return an upload target for ${file.logicalPath}.`,
-          undefined,
-          'STAGED_FILE_MINT_INCOMPLETE',
-        );
-      }
-      return upload.ref;
-    });
+    return await Promise.all(
+      directResults.map(async (result) => {
+        if ('fallbackFile' in result) {
+          const [ref] = await this.stagePlayFilesViaMultipart(
+            [result.fallbackFile],
+            'direct-egress-denied',
+          );
+          if (!ref) {
+            throw new DeeplineError(
+              `The staging server did not return an upload target for ${result.fallbackFile.logicalPath}.`,
+              undefined,
+              'STAGED_FILE_MINT_INCOMPLETE',
+            );
+          }
+          return ref;
+        }
+        return result.ref;
+      }),
+    );
   }
 
   /**
@@ -2572,11 +2602,16 @@ export class DeeplineClient {
       contentType: string;
       bytes: number;
     }>,
+    reason: 'mint-unsupported' | 'direct-egress-denied' = 'mint-unsupported',
   ): Promise<PlayStagedFileRef[]> {
     for (const file of files) {
       if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
+        const reasonMessage =
+          reason === 'direct-egress-denied'
+            ? "direct storage is blocked by this environment's network egress policy"
+            : 'the connected Deepline server does not support direct-to-storage uploads';
         throw new DeeplineError(
-          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): the connected Deepline server does not support direct-to-storage uploads, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to. Update the Deepline server (or target code.deepline.com) to stage files this large.`,
+          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): ${reasonMessage}, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to.`,
           413,
           'STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD',
           {

package/dist/bundling-sources/sdk/src/release.ts

@@ -157,7 +157,7 @@ export const SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: '0.1.317',
+  version: '0.1.318',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/cli/index.js

@@ -1037,7 +1037,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.317",
+  version: "0.1.318",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3527,6 +3527,9 @@ function stagedUploadIdentity(logicalPath, contentHash) {
 function isStagedUploadMintUnsupported(error) {
   return error instanceof DeeplineError && error.statusCode === 404;
 }
+function isStagedUploadDirectEgressDenied(error) {
+  return error instanceof DeeplineError && error.code === "STAGED_FILE_UPLOAD_EGRESS_DENIED";
+}
 function formatMegabytes(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
@@ -3547,10 +3550,11 @@ async function uploadStagedFileToPresignedUrl(input2) {
         return;
       }
       const text = await response.text().catch(() => "");
+      const egressDenied = response.status === 403 && response.headers.get("x-deny-reason")?.trim().toLowerCase() === "host_not_allowed";
       lastError = new DeeplineError(
         `Direct storage upload of ${input2.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
         response.status,
-        "STAGED_FILE_UPLOAD_FAILED",
+        egressDenied ? "STAGED_FILE_UPLOAD_EGRESS_DENIED" : "STAGED_FILE_UPLOAD_FAILED",
         { logicalPath: input2.logicalPath }
       );
       if (response.status < 500 && response.status !== 429) {
@@ -4450,7 +4454,7 @@ var DeeplineClient = class {
         upload
       );
     }
-    await Promise.all(
+    const directResults = await Promise.all(
       files.map(async (file) => {
         const upload = uploadByIdentity.get(
           stagedUploadIdentity(file.logicalPath, file.contentHash)
@@ -4463,31 +4467,45 @@ var DeeplineClient = class {
           );
         }
         if (upload.alreadyStaged || !upload.uploadUrl) {
-          return;
+          return { ref: upload.ref };
+        }
+        try {
+          await uploadStagedFileToPresignedUrl({
+            url: upload.uploadUrl,
+            headers: upload.uploadHeaders ?? {
+              "content-type": file.contentType
+            },
+            body: decodeBase64Bytes(file.contentBase64),
+            logicalPath: file.logicalPath
+          });
+          return { ref: upload.ref };
+        } catch (error) {
+          if (isStagedUploadDirectEgressDenied(error)) {
+            return { fallbackFile: file };
+          }
+          throw error;
         }
-        await uploadStagedFileToPresignedUrl({
-          url: upload.uploadUrl,
-          headers: upload.uploadHeaders ?? {
-            "content-type": file.contentType
-          },
-          body: decodeBase64Bytes(file.contentBase64),
-          logicalPath: file.logicalPath
-        });
       })
     );
-    return files.map((file) => {
-      const upload = uploadByIdentity.get(
-        stagedUploadIdentity(file.logicalPath, file.contentHash)
-      );
-      if (!upload) {
-        throw new DeeplineError(
-          `The staging server did not return an upload target for ${file.logicalPath}.`,
-          void 0,
-          "STAGED_FILE_MINT_INCOMPLETE"
-        );
-      }
-      return upload.ref;
-    });
+    return await Promise.all(
+      directResults.map(async (result) => {
+        if ("fallbackFile" in result) {
+          const [ref] = await this.stagePlayFilesViaMultipart(
+            [result.fallbackFile],
+            "direct-egress-denied"
+          );
+          if (!ref) {
+            throw new DeeplineError(
+              `The staging server did not return an upload target for ${result.fallbackFile.logicalPath}.`,
+              void 0,
+              "STAGED_FILE_MINT_INCOMPLETE"
+            );
+          }
+          return ref;
+        }
+        return result.ref;
+      })
+    );
   }
   /**
    * Mint short-lived presigned upload targets for staged play files.
@@ -4500,11 +4518,12 @@ var DeeplineClient = class {
     const response = await this.http.post("/api/v2/plays/files/stage/mint", { files });
     return response.uploads ?? [];
   }
-  async stagePlayFilesViaMultipart(files) {
+  async stagePlayFilesViaMultipart(files, reason = "mint-unsupported") {
     for (const file of files) {
       if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
+        const reasonMessage = reason === "direct-egress-denied" ? "direct storage is blocked by this environment's network egress policy" : "the connected Deepline server does not support direct-to-storage uploads";
         throw new DeeplineError(
-          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): the connected Deepline server does not support direct-to-storage uploads, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to. Update the Deepline server (or target code.deepline.com) to stage files this large.`,
+          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): ${reasonMessage}, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to.`,
           413,
           "STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD",
           {

package/dist/cli/index.mjs

@@ -1022,7 +1022,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.317",
+  version: "0.1.318",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3512,6 +3512,9 @@ function stagedUploadIdentity(logicalPath, contentHash) {
 function isStagedUploadMintUnsupported(error) {
   return error instanceof DeeplineError && error.statusCode === 404;
 }
+function isStagedUploadDirectEgressDenied(error) {
+  return error instanceof DeeplineError && error.code === "STAGED_FILE_UPLOAD_EGRESS_DENIED";
+}
 function formatMegabytes(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
@@ -3532,10 +3535,11 @@ async function uploadStagedFileToPresignedUrl(input2) {
         return;
       }
       const text = await response.text().catch(() => "");
+      const egressDenied = response.status === 403 && response.headers.get("x-deny-reason")?.trim().toLowerCase() === "host_not_allowed";
       lastError = new DeeplineError(
         `Direct storage upload of ${input2.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
         response.status,
-        "STAGED_FILE_UPLOAD_FAILED",
+        egressDenied ? "STAGED_FILE_UPLOAD_EGRESS_DENIED" : "STAGED_FILE_UPLOAD_FAILED",
         { logicalPath: input2.logicalPath }
       );
       if (response.status < 500 && response.status !== 429) {
@@ -4435,7 +4439,7 @@ var DeeplineClient = class {
         upload
       );
     }
-    await Promise.all(
+    const directResults = await Promise.all(
       files.map(async (file) => {
         const upload = uploadByIdentity.get(
           stagedUploadIdentity(file.logicalPath, file.contentHash)
@@ -4448,31 +4452,45 @@ var DeeplineClient = class {
           );
         }
         if (upload.alreadyStaged || !upload.uploadUrl) {
-          return;
+          return { ref: upload.ref };
+        }
+        try {
+          await uploadStagedFileToPresignedUrl({
+            url: upload.uploadUrl,
+            headers: upload.uploadHeaders ?? {
+              "content-type": file.contentType
+            },
+            body: decodeBase64Bytes(file.contentBase64),
+            logicalPath: file.logicalPath
+          });
+          return { ref: upload.ref };
+        } catch (error) {
+          if (isStagedUploadDirectEgressDenied(error)) {
+            return { fallbackFile: file };
+          }
+          throw error;
         }
-        await uploadStagedFileToPresignedUrl({
-          url: upload.uploadUrl,
-          headers: upload.uploadHeaders ?? {
-            "content-type": file.contentType
-          },
-          body: decodeBase64Bytes(file.contentBase64),
-          logicalPath: file.logicalPath
-        });
       })
     );
-    return files.map((file) => {
-      const upload = uploadByIdentity.get(
-        stagedUploadIdentity(file.logicalPath, file.contentHash)
-      );
-      if (!upload) {
-        throw new DeeplineError(
-          `The staging server did not return an upload target for ${file.logicalPath}.`,
-          void 0,
-          "STAGED_FILE_MINT_INCOMPLETE"
-        );
-      }
-      return upload.ref;
-    });
+    return await Promise.all(
+      directResults.map(async (result) => {
+        if ("fallbackFile" in result) {
+          const [ref] = await this.stagePlayFilesViaMultipart(
+            [result.fallbackFile],
+            "direct-egress-denied"
+          );
+          if (!ref) {
+            throw new DeeplineError(
+              `The staging server did not return an upload target for ${result.fallbackFile.logicalPath}.`,
+              void 0,
+              "STAGED_FILE_MINT_INCOMPLETE"
+            );
+          }
+          return ref;
+        }
+        return result.ref;
+      })
+    );
   }
   /**
    * Mint short-lived presigned upload targets for staged play files.
@@ -4485,11 +4503,12 @@ var DeeplineClient = class {
     const response = await this.http.post("/api/v2/plays/files/stage/mint", { files });
     return response.uploads ?? [];
   }
-  async stagePlayFilesViaMultipart(files) {
+  async stagePlayFilesViaMultipart(files, reason = "mint-unsupported") {
     for (const file of files) {
       if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
+        const reasonMessage = reason === "direct-egress-denied" ? "direct storage is blocked by this environment's network egress policy" : "the connected Deepline server does not support direct-to-storage uploads";
         throw new DeeplineError(
-          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): the connected Deepline server does not support direct-to-storage uploads, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to. Update the Deepline server (or target code.deepline.com) to stage files this large.`,
+          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): ${reasonMessage}, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to.`,
           413,
           "STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD",
           {

package/dist/index.js

@@ -760,7 +760,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.317",
+  version: "0.1.318",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3250,6 +3250,9 @@ function stagedUploadIdentity(logicalPath, contentHash) {
 function isStagedUploadMintUnsupported(error) {
   return error instanceof DeeplineError && error.statusCode === 404;
 }
+function isStagedUploadDirectEgressDenied(error) {
+  return error instanceof DeeplineError && error.code === "STAGED_FILE_UPLOAD_EGRESS_DENIED";
+}
 function formatMegabytes(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
@@ -3270,10 +3273,11 @@ async function uploadStagedFileToPresignedUrl(input) {
         return;
       }
       const text = await response.text().catch(() => "");
+      const egressDenied = response.status === 403 && response.headers.get("x-deny-reason")?.trim().toLowerCase() === "host_not_allowed";
       lastError = new DeeplineError(
         `Direct storage upload of ${input.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
         response.status,
-        "STAGED_FILE_UPLOAD_FAILED",
+        egressDenied ? "STAGED_FILE_UPLOAD_EGRESS_DENIED" : "STAGED_FILE_UPLOAD_FAILED",
         { logicalPath: input.logicalPath }
       );
       if (response.status < 500 && response.status !== 429) {
@@ -4173,7 +4177,7 @@ var DeeplineClient = class {
         upload
       );
     }
-    await Promise.all(
+    const directResults = await Promise.all(
       files.map(async (file) => {
         const upload = uploadByIdentity.get(
           stagedUploadIdentity(file.logicalPath, file.contentHash)
@@ -4186,31 +4190,45 @@ var DeeplineClient = class {
           );
         }
         if (upload.alreadyStaged || !upload.uploadUrl) {
-          return;
+          return { ref: upload.ref };
+        }
+        try {
+          await uploadStagedFileToPresignedUrl({
+            url: upload.uploadUrl,
+            headers: upload.uploadHeaders ?? {
+              "content-type": file.contentType
+            },
+            body: decodeBase64Bytes(file.contentBase64),
+            logicalPath: file.logicalPath
+          });
+          return { ref: upload.ref };
+        } catch (error) {
+          if (isStagedUploadDirectEgressDenied(error)) {
+            return { fallbackFile: file };
+          }
+          throw error;
         }
-        await uploadStagedFileToPresignedUrl({
-          url: upload.uploadUrl,
-          headers: upload.uploadHeaders ?? {
-            "content-type": file.contentType
-          },
-          body: decodeBase64Bytes(file.contentBase64),
-          logicalPath: file.logicalPath
-        });
       })
     );
-    return files.map((file) => {
-      const upload = uploadByIdentity.get(
-        stagedUploadIdentity(file.logicalPath, file.contentHash)
-      );
-      if (!upload) {
-        throw new DeeplineError(
-          `The staging server did not return an upload target for ${file.logicalPath}.`,
-          void 0,
-          "STAGED_FILE_MINT_INCOMPLETE"
-        );
-      }
-      return upload.ref;
-    });
+    return await Promise.all(
+      directResults.map(async (result) => {
+        if ("fallbackFile" in result) {
+          const [ref] = await this.stagePlayFilesViaMultipart(
+            [result.fallbackFile],
+            "direct-egress-denied"
+          );
+          if (!ref) {
+            throw new DeeplineError(
+              `The staging server did not return an upload target for ${result.fallbackFile.logicalPath}.`,
+              void 0,
+              "STAGED_FILE_MINT_INCOMPLETE"
+            );
+          }
+          return ref;
+        }
+        return result.ref;
+      })
+    );
   }
   /**
    * Mint short-lived presigned upload targets for staged play files.
@@ -4223,11 +4241,12 @@ var DeeplineClient = class {
     const response = await this.http.post("/api/v2/plays/files/stage/mint", { files });
     return response.uploads ?? [];
   }
-  async stagePlayFilesViaMultipart(files) {
+  async stagePlayFilesViaMultipart(files, reason = "mint-unsupported") {
     for (const file of files) {
       if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
+        const reasonMessage = reason === "direct-egress-denied" ? "direct storage is blocked by this environment's network egress policy" : "the connected Deepline server does not support direct-to-storage uploads";
         throw new DeeplineError(
-          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): the connected Deepline server does not support direct-to-storage uploads, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to. Update the Deepline server (or target code.deepline.com) to stage files this large.`,
+          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): ${reasonMessage}, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to.`,
           413,
           "STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD",
           {

package/dist/index.mjs

@@ -686,7 +686,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.317",
+  version: "0.1.318",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3176,6 +3176,9 @@ function stagedUploadIdentity(logicalPath, contentHash) {
 function isStagedUploadMintUnsupported(error) {
   return error instanceof DeeplineError && error.statusCode === 404;
 }
+function isStagedUploadDirectEgressDenied(error) {
+  return error instanceof DeeplineError && error.code === "STAGED_FILE_UPLOAD_EGRESS_DENIED";
+}
 function formatMegabytes(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
@@ -3196,10 +3199,11 @@ async function uploadStagedFileToPresignedUrl(input) {
         return;
       }
       const text = await response.text().catch(() => "");
+      const egressDenied = response.status === 403 && response.headers.get("x-deny-reason")?.trim().toLowerCase() === "host_not_allowed";
       lastError = new DeeplineError(
         `Direct storage upload of ${input.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
         response.status,
-        "STAGED_FILE_UPLOAD_FAILED",
+        egressDenied ? "STAGED_FILE_UPLOAD_EGRESS_DENIED" : "STAGED_FILE_UPLOAD_FAILED",
         { logicalPath: input.logicalPath }
       );
       if (response.status < 500 && response.status !== 429) {
@@ -4099,7 +4103,7 @@ var DeeplineClient = class {
         upload
       );
     }
-    await Promise.all(
+    const directResults = await Promise.all(
       files.map(async (file) => {
         const upload = uploadByIdentity.get(
           stagedUploadIdentity(file.logicalPath, file.contentHash)
@@ -4112,31 +4116,45 @@ var DeeplineClient = class {
           );
         }
         if (upload.alreadyStaged || !upload.uploadUrl) {
-          return;
+          return { ref: upload.ref };
+        }
+        try {
+          await uploadStagedFileToPresignedUrl({
+            url: upload.uploadUrl,
+            headers: upload.uploadHeaders ?? {
+              "content-type": file.contentType
+            },
+            body: decodeBase64Bytes(file.contentBase64),
+            logicalPath: file.logicalPath
+          });
+          return { ref: upload.ref };
+        } catch (error) {
+          if (isStagedUploadDirectEgressDenied(error)) {
+            return { fallbackFile: file };
+          }
+          throw error;
         }
-        await uploadStagedFileToPresignedUrl({
-          url: upload.uploadUrl,
-          headers: upload.uploadHeaders ?? {
-            "content-type": file.contentType
-          },
-          body: decodeBase64Bytes(file.contentBase64),
-          logicalPath: file.logicalPath
-        });
       })
     );
-    return files.map((file) => {
-      const upload = uploadByIdentity.get(
-        stagedUploadIdentity(file.logicalPath, file.contentHash)
-      );
-      if (!upload) {
-        throw new DeeplineError(
-          `The staging server did not return an upload target for ${file.logicalPath}.`,
-          void 0,
-          "STAGED_FILE_MINT_INCOMPLETE"
-        );
-      }
-      return upload.ref;
-    });
+    return await Promise.all(
+      directResults.map(async (result) => {
+        if ("fallbackFile" in result) {
+          const [ref] = await this.stagePlayFilesViaMultipart(
+            [result.fallbackFile],
+            "direct-egress-denied"
+          );
+          if (!ref) {
+            throw new DeeplineError(
+              `The staging server did not return an upload target for ${result.fallbackFile.logicalPath}.`,
+              void 0,
+              "STAGED_FILE_MINT_INCOMPLETE"
+            );
+          }
+          return ref;
+        }
+        return result.ref;
+      })
+    );
   }
   /**
    * Mint short-lived presigned upload targets for staged play files.
@@ -4149,11 +4167,12 @@ var DeeplineClient = class {
     const response = await this.http.post("/api/v2/plays/files/stage/mint", { files });
     return response.uploads ?? [];
   }
-  async stagePlayFilesViaMultipart(files) {
+  async stagePlayFilesViaMultipart(files, reason = "mint-unsupported") {
     for (const file of files) {
       if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
+        const reasonMessage = reason === "direct-egress-denied" ? "direct storage is blocked by this environment's network egress policy" : "the connected Deepline server does not support direct-to-storage uploads";
         throw new DeeplineError(
-          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): the connected Deepline server does not support direct-to-storage uploads, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to. Update the Deepline server (or target code.deepline.com) to stage files this large.`,
+          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): ${reasonMessage}, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to.`,
           413,
           "STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD",
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.317",
+  "version": "0.1.318",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {