> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flamedeck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NPM Package Upload

> Discover how to use the Flamedeck NPM package to programmatically upload performance traces from your JavaScript or TypeScript projects.

For programmatic trace uploads from your Node.js or browser applications, Flamedeck provides the `@flamedeck/upload` NPM package. This library offers a convenient function to send trace data directly to the Flamedeck API.

## Installation

You can install the package using npm or yarn:

```bash theme={null}
npm install @flamedeck/upload
# or
yarn add @flamedeck/upload
```

## Basic Usage

The core of the library is the `uploadTraceToApi` function. You'll need to import it along with the necessary types.

### Prerequisites

<Warning>
  **Requirements:**

  * **API Key**: You need a Flamedeck API key with `trace:upload` scope
  * **Trace Data**: Your trace data should be a `File` or `Blob` object when used in the browser, or an `ArrayBuffer` (e.g., from reading a file) when used in Node.js
  * **Filename**: The original filename for the trace
</Warning>

### Example (Node.js)

Here's a TypeScript example demonstrating how to upload a trace file from a Node.js environment:

```typescript theme={null}
import { uploadTraceToApi, UploadOptions, UploadError } from '@flamedeck/upload';
import fs from 'node:fs/promises'; // Using Node.js fs promises module
import path from 'node:path';

async function uploadMyTraceNode(filePath: string) {
  try {
    const apiKey = process.env.FLAMEDECK_API_KEY; // Recommended to use environment variables
    if (!apiKey) {
      throw new Error('FLAMEDECK_API_KEY environment variable is not set.');
    }

    const traceDataBuffer = await fs.readFile(filePath);
    const fileName = path.basename(filePath);

    const options: UploadOptions = {
      apiKey: apiKey,
      traceData: traceDataBuffer, // Pass ArrayBuffer for Node.js
      fileName: fileName,
      scenario: 'My Node.js Automated Performance Test',
      commitSha: 'abcdef1234567890',
      branch: 'main',
      notes: 'This trace was uploaded programmatically via @flamedeck/upload from Node.js.',
      folderId: 'your-optional-folder-id', // Optional: UUID of a folder
      public: true, // Optional: Make the trace publicly viewable
      // metadata: { custom_key: 'custom_value' }, // Optional
      // supabaseFunctionsUrl: 'your-custom-supabase-url' // Optional: For self-hosted or testing
    };

    console.log(`Uploading trace: ${fileName} with scenario: ${options.scenario}...`);
    const result = await uploadTraceToApi(options);

    console.log('Upload successful!');
    console.log(`Trace ID: ${result.id}`);
    console.log(`View URL: ${result.viewUrl}`);

    return result;
  } catch (error) {
    console.error('Failed to upload trace:');
    if (error instanceof UploadError) {
      console.error(`Status: ${error.status}, Message: ${error.message}`, error.details);
    } else {
      console.error('An unexpected error occurred:', error);
    }
    throw error;
  }
}

// Example usage:
// uploadMyTraceNode('/path/to/your/trace.json')
//   .then(() => console.log('Node.js upload process finished.'))
//   .catch(() => console.error('Node.js upload process failed.'));
```

### Example (Browser)

When using in a browser environment (e.g., from a file input):

```typescript theme={null}
import { uploadTraceToApi, UploadOptions, UploadError } from '@flamedeck/upload';

async function handleFileUpload(file: File) {
  const apiKey = 'YOUR_FLAMEDECK_API_KEY'; // Obtain securely

  const options: UploadOptions = {
    apiKey: apiKey,
    traceData: file, // Pass a File or Blob object directly
    fileName: file.name,
    scenario: 'Browser Upload Example',
    commitSha: 'abcdef1',
    public: false,
    metadata: { client: 'web-app', userId: 'current_user_id' }
  };

  try {
    const result = await uploadTraceToApi(options);
    console.log('Upload successful! View URL:', result.viewUrl);
    // Update UI accordingly
  } catch (error) {
    console.error('Upload failed:');
    if (error instanceof UploadError) {
      console.error(`Status: ${error.status}, Message: ${error.message}`, error.details);
      // Update UI with error details
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

// Assuming 'fileInput' is an <input type="file" /> element:
// const fileInput = document.getElementById('fileInput');
// fileInput.addEventListener('change', (event) => {
//   const file = (event.target as HTMLInputElement).files?.[0];
//   if (file) {
//     handleFileUpload(file);
//   }
// });
```

## UploadOptions Interface

The `uploadTraceToApi` function accepts an options object conforming to the `UploadOptions` interface:

<ParamField path="apiKey" type="string" required>
  Your Flamedeck API key.
</ParamField>

<ParamField path="traceData" type="Blob | ArrayBuffer" required>
  The content of the trace file. Use File/Blob for browser, ArrayBuffer for Node.js.
</ParamField>

<ParamField path="fileName" type="string" required>
  The original filename.
</ParamField>

<ParamField path="scenario" type="string" required>
  A descriptive name for the trace.
</ParamField>

<ParamField path="commitSha" type="string">
  The Git commit SHA associated with this trace.
</ParamField>

<ParamField path="branch" type="string">
  The Git branch name associated with this trace.
</ParamField>

<ParamField path="notes" type="string">
  Free-form text notes to attach to the trace.
</ParamField>

<ParamField path="folderId" type="string">
  The UUID of an existing folder to upload the trace into.
</ParamField>

<ParamField path="public" type="boolean" default="false">
  Set to `true` to make the trace publicly accessible. Defaults to `false` (private).
</ParamField>

<ParamField path="metadata" type="Record<string, unknown> | string">
  Custom key-value metadata to associate with the trace.
</ParamField>

<ParamField path="supabaseFunctionsUrl" type="string">
  Override the default Supabase functions base URL (for self-hosted or testing).
</ParamField>

<Info>
  For detailed descriptions of optional fields like `commitSha`, `branch`, `notes`, `folderId`, and `metadata`, please refer to the [CLI Upload documentation](/cli-upload#available-options), as they serve the same purpose.
</Info>

## Error Handling

The `uploadTraceToApi` function will throw an `UploadError` if the upload fails. This custom error object contains:

* `status`: HTTP status code (if applicable)
* `message`: Error message
* `details`: Additional error information from the API

<Tip>
  Always wrap your upload calls in try-catch blocks to handle potential errors gracefully.
</Tip>