@bubblystorage/sdk-js

Official JavaScript/TypeScript SDK for Bubbly Storage API

A TypeScript library for uploading files to Bubbly Storage API. Works in Node.js, Next.js, and browsers.

Installation

npm install @bubblystorage/sdk-js
# or
pnpm add @bubblystorage/sdk-js
# or
yarn add @bubblystorage/sdk-js

Quick Start

import { BubblyStorageClient } from "@bubblystorage/sdk-js";

const client = new BubblyStorageClient({
  apiKey: "your-api-key",
});

// Upload files
const result = await client.uploadFiles(files);
console.log(result.files);

Configuration Options

const client = new BubblyStorageClient({
  apiKey: "your-api-key",                   // Required: Your Bubbly Storage API key
  apiUrl: "https://api.bubblystorage.com/v1", // Optional: Custom API URL (default shown)
  isBrowser: false,                         // Optional: Set to true for browser environments
});

Usage Examples

Node.js - File Paths

// Upload from file path
await client.uploadFiles("/path/to/file.jpg");

// Multiple files
await client.uploadFiles(["/path/to/file1.jpg", "/path/to/file2.pdf"]);

Node.js - Buffers

import fs from "fs";

const buffer = fs.readFileSync("image.jpg");
// Add metadata to buffer
buffer.name = "image.jpg";
buffer.type = "image/jpeg";

await client.uploadFiles(buffer);

Browser/Next.js - File Objects

// From file input
const fileInput = document.querySelector('input[type="file"]');
await client.uploadFiles(fileInput.files[0]);

// Multiple files
await client.uploadFiles(Array.from(fileInput.files));

Next.js Server Actions

// app/upload/page.tsx
import { BubblyStorageClient } from "@bubblystorage/sdk-js";

async function uploadAction(formData: FormData) {
  "use server";

  const client = new BubblyStorageClient({
    apiKey: process.env.BUBBLYSTORAGE_API_KEY!,
  });

  const file = formData.get("file") as File;
  const result = await client.uploadFiles(file);

  return result;
}

Supported File Types

• Node.js: File paths (strings), Buffers
• Browser: File objects, Blob objects
• Next.js: File objects, Blob objects (server actions/API routes)

Error Handling

import { ValidationError, UploadError } from "@bubblystorage/sdk-js/errors";

try {
  await client.uploadFiles(files);
} catch (error) {
  if (error instanceof ValidationError) {
    console.log("Invalid file type:", error.message);
  } else if (error instanceof UploadError) {
    console.log("Upload failed:", error.message);
  }
}

TypeScript Support

Full TypeScript support with type definitions:

import type { UploadFileResponse } from "@bubblystorage/sdk-js/types";

const result: UploadFileResponse = await client.uploadFiles(files);

Requirements

• Node.js: 18+
• TypeScript: 4.5+ (optional)
• Browsers: Modern browsers with fetch support
• Next.js: 13+ (App Router recommended)

License

Apache-2.0