@bffless/artifact-client

Shared API client for BFFLESS artifact upload and download operations.

Installation

npm install @bffless/artifact-client
# or
pnpm add @bffless/artifact-client

Usage

Download artifacts

import {
  requestPrepareBatchDownload,
  downloadFilesWithPresignedUrls,
  downloadFilesDirect,
} from '@bffless/artifact-client';

// Request download manifest
const response = await requestPrepareBatchDownload(apiUrl, apiKey, {
  repository: 'owner/repo',
  path: 'coverage',
  alias: 'latest', // or commitSha, branch
});

// Download files
let result;
if (response.presignedUrlsSupported) {
  result = await downloadFilesWithPresignedUrls(response.files, outputDir);
} else {
  result = await downloadFilesDirect(apiUrl, apiKey, response.files, outputDir, {
    repository: 'owner/repo',
    alias: 'latest',
  });
}

console.log(`Downloaded ${result.success.length} files`);

Upload artifacts

import {
  requestPrepareBatchUpload,
  uploadFilesWithPresignedUrls,
  finalizeUpload,
} from '@bffless/artifact-client';
import type { FileInfo, BatchUploadFile } from '@bffless/artifact-client';

// Prepare file list
const files: FileInfo[] = [
  {
    absolutePath: '/path/to/file.js',
    relativePath: 'file.js',
    size: 1234,
    contentType: 'application/javascript',
  },
];

const batchFiles: BatchUploadFile[] = files.map((f) => ({
  path: f.relativePath,
  size: f.size,
  contentType: f.contentType,
}));

// Request presigned URLs
const response = await requestPrepareBatchUpload(apiUrl, apiKey, {
  repository: 'owner/repo',
  commitSha: 'abc123',
  branch: 'main',
  files: batchFiles,
});

if (response.presignedUrlsSupported && response.files && response.uploadToken) {
  // Upload files directly to storage
  const filesToUpload = files.map((file, i) => ({
    file,
    presignedUrl: response.files![i].presignedUrl,
  }));

  const result = await uploadFilesWithPresignedUrls(filesToUpload);
  console.log(`Uploaded ${result.success.length} files`);

  // Finalize the upload
  const finalResponse = await finalizeUpload(apiUrl, apiKey, {
    uploadToken: response.uploadToken,
  });
  console.log(`Deployment ID: ${finalResponse.deploymentId}`);
}

API Reference

Download Functions

| Function | Description | | -------------------------------- | --------------------------------------------- | | requestPrepareBatchDownload | Request download manifest with presigned URLs | | downloadFilesWithPresignedUrls | Download files using presigned URLs | | downloadFilesDirect | Download files through the API (fallback) | | downloadFileFromPresignedUrl | Download a single file from presigned URL | | downloadFileDirect | Download a single file through the API |

Upload Functions

| Function | Description | | ------------------------------ | ------------------------------------- | | requestPrepareBatchUpload | Request presigned URLs for upload | | uploadFilesWithPresignedUrls | Upload files using presigned URLs | | uploadFileToPresignedUrl | Upload a single file to presigned URL | | finalizeUpload | Finalize a batch upload |

Types

// Download types
interface PrepareBatchDownloadRequest {
  repository: string;
  path: string;
  alias?: string;
  commitSha?: string;
  branch?: string;
}

interface PrepareBatchDownloadResponse {
  presignedUrlsSupported: boolean;
  commitSha: string;
  isPublic?: boolean;
  files: DownloadFileInfo[];
}

// Upload types
interface PrepareBatchUploadRequest {
  repository: string;
  commitSha: string;
  branch?: string;
  alias?: string;
  basePath?: string;
  files: BatchUploadFile[];
}

interface PrepareBatchUploadResponse {
  presignedUrlsSupported: boolean;
  uploadToken?: string;
  files?: PresignedUrlInfo[];
}

// See src/types.ts for complete type definitions

License

See LICENSE.md