App Center File Upload Client

Common errors

• TypeError: (0 , appcenter_file_upload_client_1.FileUploadClient) is not a constructor

  cause Incorrect import statement, often when mixing CommonJS with ESM or attempting to destructure a default export incorrectly for a named export.
  fix For ESM: `import { FileUploadClient } from 'appcenter-file-upload-client';`. For CommonJS: `const { FileUploadClient } = require('appcenter-file-upload-client');`.

• An error occured: Missing required settings: assetId, assetToken, assetDomain (or similar message)

  cause The `IFileUploadClientSettings` object passed to the `upload` method is missing one or more critical properties (`assetId`, `assetDomain`, `assetToken`, or `filePath`).
  fix Ensure all required properties are populated in the settings object, obtaining `assetId`, `assetDomain`, and `assetToken` from the App Center service.

• Upload failed with status 401: Unauthorized (or similar authentication error)

  cause The `assetToken` provided is invalid, expired, or does not have the necessary permissions for the upload.
  fix Verify that the `assetToken` is fresh, correctly obtained from the App Center service, and has appropriate permissions. Check App Center's documentation for token expiry and refresh mechanisms.

Warnings

• breaking This package is at version 0.1.0 and appears to be abandoned since 2018. It is highly unstable, not actively maintained, and any internal changes to the App Center file upload service are unlikely to be reflected or supported by this client. Production use is strongly discouraged.
  Fix: Consider alternative file upload solutions or directly integrating with App Center's current file upload APIs if available and documented, bypassing this library.
• gotcha The client requires `assetId`, `assetDomain`, and `assetToken` values that must be securely obtained from the App Center file upload service itself. This library does not handle the acquisition or generation of these authentication tokens.
  Fix: Ensure your application fetches the necessary `assetId`, `assetDomain`, and `assetToken` from App Center's backend services before attempting an upload. Consult App Center documentation for how to retrieve these credentials.
• gotcha File uploads can be unreliable due to network conditions, server issues, or incorrect authentication. The library provides `onMessage` and `onStateChanged` callbacks, but robust error handling and retry mechanisms need to be implemented externally by the consumer.
  Fix: Implement comprehensive error handling in your application, including retry logic with exponential backoff for transient network issues, and clear user feedback on upload failures.

Install

• npm install appcenter-file-upload-client npm
• yarn add appcenter-file-upload-client yarn
• pnpm add appcenter-file-upload-client pnpm

Imports

• FileUploadClient
  wrong:

  const FileUploadClient = require('appcenter-file-upload-client');

  correct:

  import { FileUploadClient } from 'appcenter-file-upload-client';

  The primary class for initiating and managing file uploads. This library primarily uses named exports.
• IFileUploadClientSettings
  wrong:

  import { IFileUploadClientSettings } from 'appcenter-file-upload-client';

  correct:

  import type { IFileUploadClientSettings } from 'appcenter-file-upload-client';

  Interface for configuring the upload process. Use `import type` for type-only imports in TypeScript environments.
• IProgress
  wrong:

  import { IProgress } from 'appcenter-file-upload-client';

  correct:

  import type { IProgress } from 'appcenter-file-upload-client';

  Interface for tracking upload progress. Use `import type` for type-only imports in TypeScript environments.

Quickstart

Demonstrates initializing `FileUploadClient`, performing an upload with progress and message callbacks, and handling success or error with required environment variables.

import { FileUploadClient } from 'appcenter-file-upload-client';
import type { IProgress, MessageLevel, IUploadResults, FileUploadError } from 'appcenter-file-upload-client';

const FILE_PATH = process.env.UPLOAD_FILE_PATH ?? './sample.txt';

// These values must be obtained securely from the App Center Upload Service
// and are required for authentication and targeting the correct upload destination.
const fileUploadData = {
  assetId: process.env.APPCENTER_ASSET_ID ?? '',
  assetToken: process.env.APPCENTER_ASSET_TOKEN ?? '',
  assetUploadDomian: process.env.APPCENTER_ASSET_DOMAIN ?? ''
};

if (!fileUploadData.assetId || !fileUploadData.assetToken || !fileUploadData.assetUploadDomian || !FILE_PATH) {
  console.error('Please set UPLOAD_FILE_PATH, APPCENTER_ASSET_ID, APPCENTER_ASSET_TOKEN, and APPCENTER_ASSET_DOMAIN environment variables.');
  process.exit(1);
}

new FileUploadClient().upload({
  onMessage: (uploadMessage: string, messageLevel: MessageLevel) => {
    console.log(`[${MessageLevel[messageLevel]}] Upload message: ${uploadMessage}`);
  },
  onProgressChanged: (progressData: IProgress) => {
    console.log(`Upload progress: ${progressData.percentCompleted}%`);
  },
  assetId: fileUploadData.assetId,
  assetDomain: fileUploadData.assetUploadDomian,
  assetToken: fileUploadData.assetToken,
  filePath: FILE_PATH,
  useLogging: true
}).then((uploadResult: IUploadResults) => {
  console.log("File upload completed. Download URL:", uploadResult.downloadUrl);
}).catch((error: FileUploadError) => {
  console.error('An error occurred during upload:', error.message);
  process.exit(1);
});