Storage

Upload, download, and manage files in S3-compatible buckets.


import { EspaceTech } from "@espace-tech/sdk";
const client = new EspaceTech({ apiToken: process.env.ESPACE_TECH_TOKEN! });

Upload

Upload a file to a bucket.


// Node.js
import { readFileSync } from "fs";
const buffer = readFileSync("./photo.jpg");
await client.storage.upload("bucket-id", "images/photo.jpg", new Blob([buffer]), {
  contentType: "image/jpeg",
});
 
// Browser
const file = document.getElementById("fileInput").files[0];
await client.storage.upload("bucket-id", `uploads/${file.name}`, file);

Parameters:

Name	Type	Description
`bucketId`	`string`	Bucket ID
`key`	`string`	Object key (path)
`body`	`Blob \| File`	File content
`options.contentType`	`string?`	MIME type (auto-detected from key if omitted)

Download

Download a file’s content as a stream. Ideal for server-side usage.


const file = await client.storage.download("bucket-id", "images/photo.jpg");
 
console.log(file.contentType); // "image/jpeg"
console.log(file.size);        // 245760

Returns: DownloadResult

Property	Type	Description
`body`	`ReadableStream`	File content stream
`contentType`	`string`	MIME type
`size`	`number`	File size in bytes
`arrayBuffer()`	`Promise<ArrayBuffer>`	Read entire file into memory
`blob()`	`Promise<Blob>`	Read as Blob

Save to disk (Node.js):


import { writeFileSync } from "fs";
const file = await client.storage.download("bucket-id", "reports/q4.pdf");
writeFileSync("q4.pdf", Buffer.from(await file.arrayBuffer()));

Serve in a Next.js API route:


// app/api/files/route.ts
export async function GET(req: Request) {
  const key = new URL(req.url).searchParams.get("key")!;
  const file = await client.storage.download("bucket-id", key);
  return new Response(file.body, {
    headers: {
      "Content-Type": file.contentType,
      "Cache-Control": "public, max-age=3600",
    },
  });
}

List Objects

List files in a bucket with optional prefix filtering and pagination.


const result = await client.storage.listObjects("bucket-id", {
  prefix: "images/",
  maxKeys: 50,
});
 
for (const obj of result.objects) {
  console.log(obj.key, obj.size, obj.last_modified);
}
 
// Paginate
if (result.is_truncated) {
  const next = await client.storage.listObjects("bucket-id", {
    prefix: "images/",
    continuationToken: result.continuation_token,
  });
}

Options:

Name	Type	Default	Description
`prefix`	`string?`	—	Filter by key prefix
`delimiter`	`string?`	—	Group keys (e.g., `/` for folders)
`maxKeys`	`number?`	`100`	Max results per page
`continuationToken`	`string?`	—	Pagination token

Presigned URLs

Generate time-limited URLs that let browsers access private files directly — no proxy or API token needed.

Download URL


const { url, expires_in } = await client.storage.getDownloadUrl("bucket-id", "images/photo.jpg");
// url = "https://s3.espace-tech.com/...?X-Amz-Signature=..."
// expires_in = 3600 (seconds)

Use directly in HTML:


<img src={url} alt="Photo" />
<a href={url} download>Download PDF</a>
<video src={url} controls />

Upload URL

Let browsers upload files without exposing your API token:


const { url } = await client.storage.getUploadUrl("bucket-id", "uploads/photo.jpg", "image/jpeg");
 
// Client-side upload
await fetch(url, {
  method: "PUT",
  body: file,
  headers: { "Content-Type": "image/jpeg" },
});

Listing Images with Presigned URLs (Next.js)


// app/api/images/route.ts
import { espace } from "@/lib/espace";
 
export async function GET() {
  const result = await espace.storage.listObjects("bucket-id", { prefix: "images/" });
 
  const images = await Promise.all(
    result.objects
      .filter((obj) => !obj.is_folder)
      .map(async (obj) => ({
        key: obj.key,
        url: (await espace.storage.getDownloadUrl("bucket-id", obj.key)).url,
      }))
  );
 
  return Response.json({ images });
}
 
// Frontend: <img src={image.url} /> — no proxy needed

Delete Object


await client.storage.deleteObject("bucket-id", "images/old-photo.jpg");

Bucket Management

Create Bucket


const bucket = await client.storage.createBucket({
  name: "my-assets",
  project_id: "project-id",
});

Get Bucket


const bucket = await client.storage.getBucket("bucket-id");

List Buckets


const buckets = await client.storage.listBuckets();

Get S3 Credentials

Get raw S3 credentials for use with any S3-compatible client:


const creds = await client.storage.getCredentials("bucket-id");
console.log(creds.endpoint);       // "https://s3.espace-tech.com"
console.log(creds.access_key_id);  // "GK..."
console.log(creds.secret_key);     // "..."
console.log(creds.bucket);         // "st-myassets-a1b2c3d4"

Make Public / Private


// Make all files publicly accessible
await client.storage.makePublic("bucket-id");
 
// Restrict access (require auth)
await client.storage.makePrivate("bucket-id");

Delete Bucket


await client.storage.deleteBucket("bucket-id");