@tsdiapi/s3 NPM

@tsdiapi/s3 – AWS S3 Plugin for TSDIAPI-Server

@tsdiapi/s3 is a plugin for the TSDIAPI-Server framework that enables seamless file management with AWS S3. It supports public and private bucket configurations, allowing you to upload, retrieve, delete files, and generate presigned URLs with ease.

🚀 Features

✅ Public and Private Buckets – Manage files separately across public and private S3 buckets.
✅ Presigned URLs – Generate time-limited URLs for secure access to private files.
✅ File Uploads – Upload single or multiple files using buffers or file objects.
✅ File Deletion – Remove files from both public and private buckets.
✅ Flexible Configuration – Use inline options or environment variables for AWS credentials and bucket details.
✅ Global Provider Access – Use getS3Provider() to access S3 services from anywhere in your app.

📦 Installation

Install via NPM

npm install @tsdiapi/s3

Or Use the CLI

tsdiapi plugins add s3

🔧 Configuration & Usage

Registering the Plugin in TSDIAPI

Add the plugin to your TSDIAPI-Server setup:

import { createApp } from "@tsdiapi/server";
import createPlugin from "@tsdiapi/s3";

createApp({
  plugins: [
    createPlugin({
      publicBucketName: "your-public-bucket",
      privateBucketName: "your-private-bucket",
      accessKeyId: "your-access-key-id",
      secretAccessKey: "your-secret-access-key",
      region: "your-region",
      customHost: "your-custom-host", // Optional (CDN or custom domain)
    }),
  ],
});

Alternatively, Configure via Environment Variables

Instead of hardcoding credentials, use .env variables:

AWS_PUBLIC_BUCKET_NAME=your-public-bucket
AWS_PRIVATE_BUCKET_NAME=your-private-bucket
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=your-region
AWS_CUSTOM_HOST=your-custom-host

Then initialize without passing options:

import createPlugin from "@tsdiapi/s3";
import { createApp } from "@tsdiapi/server";

createApp({
  plugins: [createPlugin()],
});

⚙️ Plugin Options

Option	Description	Required
`publicBucketName`	Name of the public S3 bucket	No
`privateBucketName`	Name of the private S3 bucket	No
`accessKeyId`	AWS access key ID	Yes
`secretAccessKey`	AWS secret access key	Yes
`region`	AWS region	Yes
`customHost`	Custom host or CDN URL	No

Note: At least one of publicBucketName or privateBucketName must be set.

🛠 API Methods

1️⃣ Upload a File

import { getS3Provider } from "@tsdiapi/s3";

const s3 = getS3Provider();
const response = await s3.uploadFile(
  "your-public-bucket",
  "example.png",
  fileBuffer,
  "image/png"
);

console.log(response.url);

2️⃣ Upload Multiple Files

const responses = await getS3Provider().uploadFiles(fileArray);

3️⃣ Delete a File

await getS3Provider().deleteFile("path/to/file.png", false);

4️⃣ Generate a Presigned URL

const presignedUrl = await getS3Provider().getPresignedUrl("path/to/file.png", true);

5️⃣ Get Public URL

const publicUrl = getS3Provider().getPublicURL("path/to/file.png");

🔄 Example Workflow

1️⃣ Upload Files → Upload files to public or private buckets.
2️⃣ Access Secure Files → Use presigned URLs to grant secure, temporary access to private files.
3️⃣ Batch Operations → Upload and manage multiple files at once.

⚠️ Error Handling

All methods include built-in error handling and logging:

try {
  const response = await getS3Provider().uploadFile(
    "your-public-bucket",
    "example.pdf",
    fileBuffer,
    "application/pdf"
  );
  console.log("File uploaded successfully:", response);
} catch (error) {
  console.error("File upload failed:", error);
}

🌐 Standalone Usage (Without TSDIAPI)

You can also use @tsdiapi/s3 outside of TSDIAPI-Server:

import { S3Provider } from "@tsdiapi/s3";

const s3 = new S3Provider();
s3.init({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    region: "your-region",
});

await s3.uploadFile("your-bucket", "example.txt", Buffer.from("Hello, S3!"), "text/plain");