@storage4everyone/sdk

Official TypeScript / JavaScript SDK for Storage4Everyone — Plug & Play Cloud Object Storage.

⚡ Quickstart

1. Installation

npm install @storage4everyone/sdk

Or with pnpm / yarn / bun:

pnpm add @storage4everyone/sdk
# or
bun add @storage4everyone/sdk

2. Configure Your 2 Keys

Add the two required environment variables to your project's .env file:

# .env
S4E_API_KEY=s4e_live_your_api_key_here
S4E_BUCKET=s4e://workspace-01/test-bucket

Zero Extra Config: You do not need to configure endpoints, base URLs, or complex AWS credentials. The SDK automatically detects your workspace and bucket from the s4e:// URI format!

3. Usage

import { Storage4Everyone } from "@storage4everyone/sdk";

// Plug & play: Automatically reads S4E_API_KEY and S4E_BUCKET from process.env!
const s4e = new Storage4Everyone();

// 1. Upload a file (supports Buffer, Stream, Blob, string, or Uint8Array)
await s4e.upload("documents/invoice.pdf", fileBuffer);

// 2. Download a file
const file = await s4e.download("documents/invoice.pdf");
console.log(await file.text());

// 3. Generate a temporary download link (e.g. 15 minutes / 900 seconds)
const downloadUrl = await s4e.getDownloadUrl("documents/invoice.pdf", { expiresIn: 900 });
console.log("Download link:", downloadUrl);

// 4. List all files in your bucket
const { objects, count, totalBytes } = await s4e.list();
console.log(`Found ${count} files (${totalBytes} bytes)`);

// 5. Delete a file (automatically protected with soft-delete Trash Bin on paid tiers)
await s4e.delete("documents/invoice.pdf");

📂 Working with Multiple Buckets

You can target another bucket at any time without creating a new client:

// Target an avatars bucket
const avatars = s4e.bucket("s4e://workspace-01/avatars");

await avatars.upload("user_123.png", avatarBuffer);

🌐 Client-Side Direct Uploads (Presigned URLs)

To allow browser clients to upload directly to storage without passing files through your web server:

// On your server (e.g. Next.js API route or Express backend)
app.post("/api/get-upload-url", async (req, res) => {
  const { url } = await s4e.getUploadUrl("uploads/user-video.mp4", {
    contentType: "video/mp4",
    expiresIn: 900,
  });
  res.json({ uploadUrl: url });
});

// In your frontend client (browser)
const { uploadUrl } = await fetch("/api/get-upload-url").then(r => r.json());

// Direct PUT straight to Backblaze B2 storage
await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "video/mp4" },
  body: selectedVideoFile,
});

🚀 Guide: Setting Up and Publishing to npmjs.com

Follow these steps to publish storage4everyone to the official npm registry:

Step 1: Create an npmjs.com Account

1. Visit https://www.npmjs.com/signup and create your account.
2. Verify your email address.
3. Enable Two-Factor Authentication (2FA) in Account Settings → 2FA.

Step 2: Log In to npm via Terminal

In your terminal, authenticate with your npm account:

npm login

Follow the prompts to enter your username, password, and 2FA code (or one-time browser login).

Step 3: Verify Your Identity

Run:

npm whoami

It should print your npm username.

Step 4: Build the Package

Inside the storage4everyone directory:

cd storage4everyone
npm install
npm run build

Step 5: Publish to npm

Publish the package with public access:

npm publish --access public

Once published, anyone in the world will be able to install it instantly via:

npm install @storage4everyone/sdk

📄 License

Apache-2.0 © Storage4Everyone