Server Storage

The server Storage client uses a Carpo project API key with the storage scope. This is a privileged credential. It bypasses end user bucket policies and has full access to the configured bucket, so keep it in server only configuration.

const usage = await carpo.storage.getUsage()
const objects = await carpo.storage.listObjects({ prefix: 'exports/' })

The server client includes the same object, metadata, download, upload, multipart, copy, move, and recovery methods as the browser Storage client. It adds getUsage(), which returns the bucket settings, configured quota, current use, reservations, and a note.

The project API key is sent to the Carpo API. File bytes still transfer through short lived signed R2 URLs. The SDK does not require direct R2 credentials.

Create a standalone server Storage client with createCarpoServerStorageClient() from @carpodev/carpo-sdk/server/storage:

import { createCarpoServerStorageClient } from '@carpodev/carpo-sdk/server/storage'

const storage = createCarpoServerStorageClient({
  apiUrl: process.env.CARPO_API_URL!,
  projectId: process.env.CARPO_PROJECT_ID!,
  environment: 'production',
  bucketId: process.env.CARPO_STORAGE_BUCKET_ID!,
  apiKey: () => process.env.CARPO_STORAGE_API_KEY!,
})

apiKey can be a key string or a function that returns the current key. Use a provider when a deployment rotates the key without recreating the client. Do not return the API key to a browser or include it in logs.

If a server request should be limited by an end user's Storage policy, use createCarpoServerRequestClient() instead. That client uses the incoming user identity and does not accept a project server key.