UploadOps SDK

TypeScript SDK for processing files with UploadOps pipelines.

Installation

npm install uploadops-sdk
# or
pnpm add uploadops-sdk
# or
bun add uploadops-sdk

Quick Start

import { UploadOpsClient } from "uploadops-sdk";

const client = new UploadOpsClient("your-api-key");

// Process a file through a pipeline
const result = await client.process(file, "my-image-pipeline");

console.log(result.type); // "image/webp" — output content type

Usage

Browser

const input = document.querySelector<HTMLInputElement>("#file-input");

input.addEventListener("change", async () => {
  const file = input.files?.[0];
  if (!file) return;

  const result = await client.process(file, "compress-images");
  
  // Use the processed file
  const url = URL.createObjectURL(result);
  document.querySelector("img").src = url;
});

Node.js / Bun

import { readFile, writeFile } from "fs/promises";
import { UploadOpsClient } from "uploadops-sdk";

const client = new UploadOpsClient("your-api-key");

const buffer = await readFile("input.png");

const result = await client.process(
  { data: buffer, fileName: "input.png", contentType: "image/png" },
  "optimize-images"
);

// Convert Blob to Buffer and save
const outputBuffer = Buffer.from(await result.arrayBuffer());
await writeFile("output.webp", outputBuffer);

API Reference

UploadOpsClient

Constructor

new UploadOpsClient(apiKey: string)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | Yes | Your UploadOps API key |

process(file, pipelineName)

Process a file through a pipeline.

process(file: FileInput, pipelineName: string): Promise<Blob>

| Parameter | Type | Description | |-----------|------|-------------| | file | FileInput | The file to process | | pipelineName | string | Name of the pipeline to run |

Returns: Promise<Blob> — The processed file. Access blob.type for the output content type.

FileInput

The SDK accepts multiple input formats:

type FileInput =
  | File                      // Browser File object
  | Blob                      // Browser Blob object
  | {
      data: Buffer | Uint8Array | ArrayBuffer;
      fileName: string;
      contentType?: string;   // Defaults to "application/octet-stream"
    };

Error Handling

The SDK throws typed errors for different failure scenarios:

import {
  UploadOpsClient,
  UploadOpsError,
  AuthenticationError,
  RateLimitError,
  ProcessingError,
  UploadError,
} from "uploadops-sdk";

try {
  const result = await client.process(file, "my-pipeline");
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing API key (401)
    console.error("Auth failed:", error.message);
  } else if (error instanceof RateLimitError) {
    // Too many requests (429)
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ProcessingError) {
    // Pipeline processing failed
    console.error("Processing failed:", error.message);
    console.error("Category:", error.category);
    console.error("Retryable:", error.retryable);
    
    if (error.metadata) {
      console.error("Details:", error.metadata.details);
    }
  } else if (error instanceof UploadError) {
    // File upload failed
    console.error("Upload failed:", error.message);
  } else if (error instanceof UploadOpsError) {
    // Other API errors
    console.error("Error:", error.message, error.statusCode);
  }
}

Error Types

| Error | Status | Description | |-------|--------|-------------| | AuthenticationError | 401 | Invalid or missing API key | | RateLimitError | 429 | Rate limit exceeded (500 requests/hour) | | ProcessingError | 400, 500, 502, 503 | Pipeline processing failed | | UploadError | — | File upload failed | | UploadOpsError | — | Base error class for all errors |

ProcessingError Categories

When a ProcessingError is thrown, check the category property:

| Category | Description | Retryable | |----------|-------------|-----------| | VALIDATION_ERROR | File is invalid (size, format, dimensions) | No | | PIPELINE_ERROR | Pipeline node execution failed | No | | SYSTEM_ERROR | Infrastructure failure | Yes | | CONFIGURATION_ERROR | Pipeline is misconfigured | No |

if (error instanceof ProcessingError) {
  if (error.category === "VALIDATION_ERROR") {
    // File doesn't meet pipeline requirements
    // Check error.metadata.details for specifics
  } else if (error.category === "SYSTEM_ERROR" && error.retryable) {
    // Transient failure — safe to retry
  }
}

Validation Error Codes

When category is VALIDATION_ERROR, the metadata.details.errors array contains specific validation failures:

| Code | Description | |------|-------------| | EMPTY_FILE | File is empty | | FILE_TOO_LARGE | File exceeds size limit | | FILE_TOO_SMALL | File below minimum size | | INVALID_FORMAT | Unsupported file format | | WIDTH_TOO_LARGE | Image width exceeds limit | | WIDTH_TOO_SMALL | Image width below minimum | | HEIGHT_TOO_LARGE | Image height exceeds limit | | HEIGHT_TOO_SMALL | Image height below minimum | | INVALID_IMAGE | Cannot parse as valid image |

Rate Limits

| Limit | Window | |-------|--------| | 500 requests | per hour |

When rate limited, a RateLimitError is thrown with a retryAfter property indicating seconds until the limit resets.

License

MIT