@devicecloud.dev/dcd 4.4.9 → 5.0.0-beta.0

package/dist/gateways/api-gateway.js

@@ -1,7 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiGateway = void 0;
+exports.ApiGateway = exports.ApiError = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const path = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+/**
+ * Error thrown for non-OK API responses, carrying the HTTP status so callers
+ * can branch on auth failures etc. without string matching.
+ */
+class ApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+    }
+}
+exports.ApiError = ApiError;
+/**
+ * Parses a successful response body as JSON, wrapping parse failures in a
+ * descriptive error (a 200 with an HTML body otherwise surfaces as a bare
+ * SyntaxError with no context about which call failed).
+ */
+async function parseJsonResponse(res, operation) {
+    try {
+        return (await res.json());
+    }
+    catch (error) {
+        throw new Error(`${operation}: API returned an invalid JSON response (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
 exports.ApiGateway = {
     /**
      * Enhances generic "fetch failed" errors with more specific diagnostic information
@@ -51,51 +81,82 @@ exports.ApiGateway = {
         // Add context and improve readability
         switch (res.status) {
             case 400: {
-                throw new Error(`Invalid request: ${userMessage}`);
+                throw new ApiError(`Invalid request: ${userMessage}`, 400);
             }
             case 401: {
-                throw new Error(`Authentication failed. Please check your API key.`);
+                // Auth-mode-neutral: the CLI accepts both API keys and Bearer sessions.
+                // status.ts matches on the "Authentication failed" / "API key" substrings.
+                let message = `Authentication failed — your credentials are invalid or expired. ` +
+                    `Re-run \`dcd login\` or check your API key. (${operation})`;
+                if (userMessage) {
+                    message += `\nServer response: ${userMessage}`;
+                }
+                throw new ApiError(message, 401);
             }
             case 403: {
                 // For 403, use the server's error message directly as it's now detailed
                 // If the message suggests an API key issue, provide additional guidance
                 if (userMessage.toLowerCase().includes('api key')) {
-                    throw new Error(`${userMessage}\n\nTroubleshooting steps:\n` +
+                    throw new ApiError(`${userMessage}\n\nTroubleshooting steps:\n` +
                         `  1. Verify DEVICE_CLOUD_API_KEY environment variable is set\n` +
                         `  2. Check you're using the correct API key for this environment\n` +
                         `  3. Ensure the API key hasn't been deleted or revoked\n` +
-                        `  4. Confirm you're connecting to the correct API URL`);
+                        `  4. Confirm you're connecting to the correct API URL`, 403);
                 }
-                throw new Error(`Access denied. ${userMessage}`);
+                throw new ApiError(`Access denied. ${userMessage}`, 403);
             }
             case 404: {
-                throw new Error(`Resource not found. ${userMessage}`);
+                throw new ApiError(`Resource not found. ${userMessage}`, 404);
             }
             case 429: {
-                throw new Error(`Rate limit exceeded. Please try again later.`);
+                throw new ApiError(`Rate limit exceeded. Please try again later. (${operation})`, 429);
             }
             case 500: {
-                throw new Error(`Server error occurred. Please try again or contact support.`);
+                throw new ApiError(`Server error occurred. Please try again or contact support. (${operation})`, 500);
             }
             default: {
-                throw new Error(`${operation} failed: ${userMessage} (HTTP ${res.status})`);
+                // `operation` is already phrased as "Failed to …", so don't append
+                // another "failed" here (avoids "Failed to execute test failed: …").
+                throw new ApiError(`${operation}: ${userMessage} (HTTP ${res.status})`, res.status);
             }
         }
     },
-    async checkForExistingUpload(baseUrl, apiKey, sha) {
+    /**
+     * Streams a fetch response body to disk, expanding a leading tilde and
+     * creating the destination directory if needed. Internal helper shared by
+     * the download methods.
+     */
+    async streamResponseToFile(res, destinationPath, operation) {
+        if (res.body === null) {
+            throw new Error(`${operation}: server response contained no body to download`);
+        }
+        // Handle tilde expansion for home directory
+        const expandedPath = destinationPath.replace(/^~(?=$|\/|\\)/, (0, node_os_1.homedir)());
+        // Create directory structure if it doesn't exist
+        const directory = path.dirname(expandedPath);
+        if (directory !== '.') {
+            (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+        }
+        // Use 'w' flag to overwrite existing files instead of failing.
+        // pipeline (unlike .pipe) propagates source-stream errors, so a
+        // mid-download network failure rejects instead of hanging forever.
+        const fileStream = (0, node_fs_1.createWriteStream)(expandedPath, { flags: 'w' });
+        await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(res.body), fileStream);
+    },
+    async checkForExistingUpload(baseUrl, auth, sha) {
         try {
             const res = await fetch(`${baseUrl}/uploads/checkForExistingUpload`, {
                 body: JSON.stringify({ sha }),
                 headers: {
                     'content-type': 'application/json',
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'POST',
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to check for existing upload');
             }
-            return res.json();
+            return await parseJsonResponse(res, 'Failed to check for existing upload');
         }
         catch (error) {
             // Handle network-level errors (DNS, connection refused, timeout, etc.)
@@ -105,48 +166,20 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async downloadArtifactsZip(baseUrl, apiKey, uploadId, results, artifactsPath = './artifacts.zip') {
+    async downloadArtifactsZip(baseUrl, auth, uploadId, results, artifactsPath = './artifacts.zip') {
         try {
             const res = await fetch(`${baseUrl}/results/${uploadId}/download`, {
                 body: JSON.stringify({ results }),
                 headers: {
                     'content-type': 'application/json',
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'POST',
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to download artifacts');
             }
-            // Handle tilde expansion for home directory
-            if (artifactsPath.startsWith('~/') || artifactsPath === '~') {
-                artifactsPath = artifactsPath.replace(/^~(?=$|\/|\\)/, 
-                // eslint-disable-next-line unicorn/prefer-module
-                require('node:os').homedir());
-            }
-            // Create directory structure if it doesn't exist
-            // eslint-disable-next-line unicorn/prefer-module
-            const { dirname } = require('node:path');
-            // eslint-disable-next-line unicorn/prefer-module
-            const { createWriteStream, mkdirSync } = require('node:fs');
-            // eslint-disable-next-line unicorn/prefer-module
-            const { finished } = require('node:stream/promises');
-            // eslint-disable-next-line unicorn/prefer-module
-            const { Readable } = require('node:stream');
-            const directory = dirname(artifactsPath);
-            if (directory !== '.') {
-                try {
-                    mkdirSync(directory, { recursive: true });
-                }
-                catch (error) {
-                    // Ignore if directory already exists
-                    if (error.code !== 'EEXIST') {
-                        throw error;
-                    }
-                }
-            }
-            const fileStream = createWriteStream(artifactsPath, { flags: 'w' });
-            await finished(Readable.fromWeb(res.body).pipe(fileStream));
+            await this.streamResponseToFile(res, artifactsPath, 'Failed to download artifacts');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -156,7 +189,7 @@ exports.ApiGateway = {
         }
     },
     async finaliseUpload(config) {
-        const { baseUrl, apiKey, id, metadata, path, sha, supabaseSuccess, backblazeSuccess, bytes } = config;
+        const { baseUrl, auth, id, metadata, path, sha, supabaseSuccess, backblazeSuccess, bytes } = config;
         try {
             const res = await fetch(`${baseUrl}/uploads/finaliseUpload`, {
                 body: JSON.stringify({
@@ -165,19 +198,19 @@ exports.ApiGateway = {
                     id,
                     metadata,
                     path, // This is tempPath for TUS uploads
-                    sha,
+                    ...(sha ? { sha } : {}),
                     supabaseSuccess,
                 }),
                 headers: {
                     'content-type': 'application/json',
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'POST',
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to finalize upload');
             }
-            return res.json();
+            return await parseJsonResponse(res, 'Failed to finalize upload');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -186,20 +219,20 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async getBinaryUploadUrl(baseUrl, apiKey, platform, fileSize) {
+    async getBinaryUploadUrl(baseUrl, auth, platform, fileSize) {
         try {
             const res = await fetch(`${baseUrl}/uploads/getBinaryUploadUrl`, {
                 body: JSON.stringify({ platform, fileSize }),
                 headers: {
                     'content-type': 'application/json',
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'POST',
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to get upload URL');
             }
-            return res.json();
+            return await parseJsonResponse(res, 'Failed to get upload URL');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -208,20 +241,20 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async finishLargeFile(baseUrl, apiKey, fileId, partSha1Array) {
+    async finishLargeFile(baseUrl, auth, fileId, partSha1Array) {
         try {
             const res = await fetch(`${baseUrl}/uploads/finishLargeFile`, {
                 body: JSON.stringify({ fileId, partSha1Array }),
                 headers: {
                     'content-type': 'application/json',
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'POST',
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to finish large file');
             }
-            return res.json();
+            return await parseJsonResponse(res, 'Failed to finish large file');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -230,16 +263,16 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async getResultsForUpload(baseUrl, apiKey, uploadId) {
+    async getResultsForUpload(baseUrl, auth, uploadId) {
         // TODO: merge with getUploadStatus
         try {
             const res = await fetch(`${baseUrl}/results/${uploadId}`, {
-                headers: { 'x-app-api-key': apiKey },
+                headers: { ...auth.headers },
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to get results');
             }
-            return res.json();
+            return await parseJsonResponse(res, 'Failed to get results');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -248,7 +281,7 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async getUploadStatus(baseUrl, apiKey, options) {
+    async getUploadStatus(baseUrl, auth, options) {
         const queryParams = new URLSearchParams();
         if (options.uploadId) {
             queryParams.append('uploadId', options.uploadId);
@@ -259,13 +292,13 @@ exports.ApiGateway = {
         try {
             const response = await fetch(`${baseUrl}/uploads/status?${queryParams}`, {
                 headers: {
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
             });
             if (!response.ok) {
                 await this.handleApiError(response, 'Failed to get upload status');
             }
-            return response.json();
+            return await parseJsonResponse(response, 'Failed to get upload status');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -274,7 +307,7 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async listUploads(baseUrl, apiKey, options = {}) {
+    async listUploads(baseUrl, auth, options = {}) {
         const queryParams = new URLSearchParams();
         if (options.name) {
             queryParams.append('name', options.name);
@@ -295,13 +328,13 @@ exports.ApiGateway = {
         try {
             const response = await fetch(url, {
                 headers: {
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
             });
             if (!response.ok) {
                 await this.handleApiError(response, 'Failed to list uploads');
             }
-            return response.json();
+            return await parseJsonResponse(response, 'Failed to list uploads');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -310,19 +343,19 @@ exports.ApiGateway = {
             throw error;
         }
     },
-    async uploadFlow(baseUrl, apiKey, testFormData) {
+    async uploadFlow(baseUrl, auth, testFormData) {
         try {
             const res = await fetch(`${baseUrl}/uploads/flow`, {
                 body: testFormData,
                 headers: {
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'POST',
             });
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to upload test flows');
             }
-            return res.json();
+            return await parseJsonResponse(res, 'Failed to upload test flows');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -334,13 +367,13 @@ exports.ApiGateway = {
     /**
      * Generic report download method that handles both junit and allure reports
      * @param baseUrl - API base URL
-     * @param apiKey - API key for authentication
+     * @param auth - AuthContext (API key or Bearer session) for authentication
      * @param uploadId - Upload ID to download report for
      * @param reportType - Type of report to download ('junit' or 'allure')
      * @param reportPath - Optional custom path for the downloaded report
      * @returns Promise that resolves when download is complete
      */
-    async downloadReportGeneric(baseUrl, apiKey, uploadId, reportType, reportPath) {
+    async downloadReportGeneric(baseUrl, auth, uploadId, reportType, reportPath) {
         // Define endpoint and default filename mappings
         const config = {
             junit: {
@@ -369,7 +402,7 @@ exports.ApiGateway = {
             // Make the download request
             const res = await fetch(url, {
                 headers: {
-                    'x-app-api-key': apiKey,
+                    ...auth.headers,
                 },
                 method: 'GET',
             });
@@ -380,38 +413,145 @@ exports.ApiGateway = {
                 }
                 throw new Error(`${errorPrefix}: ${res.status} ${errorText}`);
             }
-            // Handle tilde expansion for home directory (applies to all report types)
-            let expandedPath = finalReportPath;
-            if (finalReportPath.startsWith('~/') || finalReportPath === '~') {
-                expandedPath = finalReportPath.replace(/^~/, 
-                // eslint-disable-next-line unicorn/prefer-module
-                require('node:os').homedir());
-            }
-            // Create directory structure if it doesn't exist
-            // eslint-disable-next-line unicorn/prefer-module
-            const { dirname } = require('node:path');
-            // eslint-disable-next-line unicorn/prefer-module
-            const { createWriteStream, mkdirSync } = require('node:fs');
-            // eslint-disable-next-line unicorn/prefer-module
-            const { finished } = require('node:stream/promises');
-            // eslint-disable-next-line unicorn/prefer-module
-            const { Readable } = require('node:stream');
-            const directory = dirname(expandedPath);
-            if (directory !== '.') {
-                try {
-                    mkdirSync(directory, { recursive: true });
-                }
-                catch (error) {
-                    // Ignore EEXIST errors (directory already exists)
-                    if (error.code !== 'EEXIST') {
-                        throw error;
-                    }
-                }
+            await this.streamResponseToFile(res, finalReportPath, errorPrefix);
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, url);
+            }
+            throw error;
+        }
+    },
+    async startLiveSession(baseUrl, auth, params) {
+        try {
+            const res = await fetch(`${baseUrl}/live`, {
+                body: JSON.stringify({
+                    binaryUploadId: params.binaryUploadId,
+                    deviceLocale: params.deviceLocale,
+                    platform: params.platform,
+                    androidDevice: params.androidDevice,
+                    androidApiLevel: params.androidApiLevel,
+                }),
+                headers: {
+                    'content-type': 'application/json',
+                    ...auth.headers,
+                },
+                method: 'POST',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to start live session');
+            }
+            return await parseJsonResponse(res, 'Failed to start live session');
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, `${baseUrl}/live`);
+            }
+            throw error;
+        }
+    },
+    async installLiveBinary(baseUrl, auth, sessionName, binaryUploadId) {
+        const url = `${baseUrl}/live/${sessionName}/install`;
+        try {
+            const res = await fetch(url, {
+                body: JSON.stringify({ binaryUploadId }),
+                headers: {
+                    'content-type': 'application/json',
+                    ...auth.headers,
+                },
+                method: 'POST',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to install binary');
+            }
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, url);
+            }
+            throw error;
+        }
+    },
+    async execLiveYaml(baseUrl, auth, sessionName, yaml, opts = {}) {
+        const url = `${baseUrl}/live/${sessionName}/exec`;
+        try {
+            const res = await fetch(url, {
+                body: JSON.stringify({ yaml, async: opts.async }),
+                headers: {
+                    'content-type': 'application/json',
+                    ...auth.headers,
+                },
+                method: 'POST',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to execute test');
+            }
+            return await parseJsonResponse(res, 'Failed to execute test');
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, url);
+            }
+            throw error;
+        }
+    },
+    async getLiveCommand(baseUrl, auth, sessionName, commandId) {
+        const url = `${baseUrl}/live/${sessionName}/commands/${commandId}`;
+        try {
+            const res = await fetch(url, { headers: { ...auth.headers }, method: 'GET' });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to get command status');
+            }
+            return await parseJsonResponse(res, 'Failed to get command status');
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, url);
+            }
+            throw error;
+        }
+    },
+    async keepaliveLiveSession(baseUrl, auth, sessionName) {
+        const url = `${baseUrl}/live/${sessionName}/keepalive`;
+        try {
+            const res = await fetch(url, { headers: { ...auth.headers }, method: 'POST' });
+            // A keepalive failure shouldn't kill a long-running poll; swallow non-OK.
+            if (!res.ok)
+                return;
+        }
+        catch {
+            // best effort
+        }
+    },
+    async stopLiveSession(baseUrl, auth, sessionName) {
+        const url = `${baseUrl}/live/${sessionName}`;
+        try {
+            const res = await fetch(url, {
+                headers: { ...auth.headers },
+                method: 'DELETE',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to stop session');
+            }
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, url);
+            }
+            throw error;
+        }
+    },
+    async getLiveSession(baseUrl, auth, sessionName) {
+        const url = `${baseUrl}/live/${sessionName}`;
+        try {
+            const res = await fetch(url, {
+                headers: { ...auth.headers },
+                method: 'GET',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to get session status');
             }
-            // Write the file using streaming for better memory efficiency
-            // Use 'w' flag to overwrite existing files instead of failing
-            const fileStream = createWriteStream(expandedPath, { flags: 'w' });
-            await finished(Readable.fromWeb(res.body).pipe(fileStream));
+            return await parseJsonResponse(res, 'Failed to get session status');
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {

package/dist/gateways/cli-auth-gateway.d.ts

@@ -0,0 +1,13 @@
+import type { StoredSession } from '../utils/config-store';
+export interface RefreshedSession {
+    access_token: string;
+    refresh_token: string;
+    /** Unix epoch seconds. */
+    expires_at: number;
+    user_email: string;
+    user_id: string;
+}
+export declare const CliAuthGateway: {
+    refresh(supabaseUrl: string, supabaseAnonKey: string, session: StoredSession): Promise<RefreshedSession>;
+    signOut(supabaseUrl: string, supabaseAnonKey: string, session: StoredSession): Promise<void>;
+};

package/dist/gateways/cli-auth-gateway.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliAuthGateway = void 0;
+/**
+ * Supabase session operations for the CLI: refresh an expired access token
+ * and sign-out (best-effort revocation on the Supabase side).
+ *
+ * Does not talk to the dcd API — the dcd-side session exchange lives in the
+ * login command's loopback flow, where the frontend POSTs ciphertext back.
+ */
+const supabase_js_1 = require("@supabase/supabase-js");
+function client(supabaseUrl, supabaseAnonKey) {
+    return (0, supabase_js_1.createClient)(supabaseUrl, supabaseAnonKey, {
+        auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+    });
+}
+exports.CliAuthGateway = {
+    async refresh(supabaseUrl, supabaseAnonKey, session) {
+        const sb = client(supabaseUrl, supabaseAnonKey);
+        const { data, error } = await sb.auth.refreshSession({
+            refresh_token: session.refresh_token,
+        });
+        if (error || !data.session || !data.user) {
+            throw new Error(`Failed to refresh session: ${error?.message ?? 'no session returned'}. ` +
+                `Run \`dcd login\` again.`);
+        }
+        const s = data.session;
+        const u = data.user;
+        if (!s.expires_at)
+            throw new Error('Refreshed session is missing expires_at');
+        return {
+            access_token: s.access_token,
+            refresh_token: s.refresh_token,
+            expires_at: s.expires_at,
+            user_email: u.email ?? session.user_email,
+            user_id: u.id,
+        };
+    },
+    async signOut(supabaseUrl, supabaseAnonKey, session) {
+        // `scope: 'local'` clears this client's SDK state only — no server call,
+        // no revocation. supabase-js defaults to `scope: 'global'`, which revokes
+        // EVERY session for the user (browser, mobile, other CLIs), so
+        // `dcd logout` would kick the user out of the web app. We don't want
+        // that — logging out locally should be local.
+        const sb = client(supabaseUrl, supabaseAnonKey);
+        try {
+            await sb.auth.setSession({
+                access_token: session.access_token,
+                refresh_token: session.refresh_token,
+            });
+            await sb.auth.signOut({ scope: 'local' });
+        }
+        catch {
+            // Best effort — the local config will be wiped regardless.
+        }
+    },
+};

package/dist/gateways/supabase-gateway.d.ts

@@ -1,25 +1,25 @@
+import { type DcdEnvName } from '../config/environments';
+/** Disk-backed upload descriptor — see UploadSource in src/methods.ts. */
+export interface ResumableUploadSource {
+    contentType: string;
+    diskPath: string;
+    name: string;
+    size: number;
+}
 export declare class SupabaseGateway {
-    private static SB;
-    static getSupabaseKeys(env: 'dev' | 'prod'): {
-        SUPABASE_PUBLIC_KEY: string;
-        SUPABASE_URL: string;
-    } | {
-        SUPABASE_PUBLIC_KEY: string;
-        SUPABASE_URL: string;
-    };
     /**
      * Upload to Supabase using resumable uploads (TUS protocol)
      * Uploads to staging location (uploads/{id}/) using anon key
      * File is later moved to final location by API after finalization
      * @param env - Environment (dev or prod)
      * @param path - Staging storage path (uploads/{id}/file.ext)
-     * @param file - File to upload
+     * @param source - Upload source descriptor; the file is streamed from disk
      * @param debug - Enable debug logging
      * @param onProgress - Optional callback for upload progress (bytesUploaded, bytesTotal)
      * @returns Promise that resolves when upload completes
      */
-    static uploadResumable(env: 'dev' | 'prod', path: string, file: File, debug?: boolean, onProgress?: (bytesUploaded: number, bytesTotal: number) => void): Promise<void>;
-    static uploadToSignedUrl(env: 'dev' | 'prod', path: string, token: string, file: File, debug?: boolean): Promise<void>;
+    static uploadResumable(env: DcdEnvName, path: string, source: ResumableUploadSource, debug?: boolean, onProgress?: (bytesUploaded: number, bytesTotal: number) => void): Promise<void>;
+    static uploadToSignedUrl(env: DcdEnvName, path: string, token: string, file: File, debug?: boolean): Promise<void>;
     /**
      * Logs network error details for debugging
      * @param error - Error object to analyze for network-related issues