@venturekit/storage API

Storage Client

The storage client provides a full-featured S3-compatible API that works with both AWS S3 (production) and MinIO (local dev). It auto-detects the environment.

`createStorageClient(config)`

Create a storage client with explicit configuration.

import { createStorageClient } from '@venturekit/storage';

const storage = createStorageClient({
  bucket: 'my-uploads',
  prefix: 'tenant-123/', // optional key prefix
});

Config options:

Option	Type	Description
`bucket`	`string`	S3 bucket name (required)
`region`	`string`	AWS region (default: `AWS_REGION` env var)
`endpoint`	`string`	Custom S3 endpoint (auto-set for MinIO locally)
`forcePathStyle`	`boolean`	Force path-style URLs (auto-set for MinIO)
`prefix`	`string`	Key prefix for all operations
`credentials`	`object`	AWS credentials (uses default chain if omitted)

`createStorageClientFromEnv(overrides?)`

Create a storage client from environment variables. Reads VENTURE_STORAGE_BUCKET, VENTURE_STORAGE_PREFIX, and MinIO config from env.

import { createStorageClientFromEnv } from '@venturekit/storage';

const storage = createStorageClientFromEnv();

StorageClient Methods

Method	Description
`put(key, body, options?)`	Upload data (Buffer, string, or stream)
`get(key, options?)`	Download data as Buffer
`getStream(key, options?)`	Download data as readable stream
`head(key)`	Get object metadata without downloading
`delete(key)`	Delete an object
`deleteMany(keys)`	Delete multiple objects
`copy(src, dest, options?)`	Copy an object
`move(src, dest, options?)`	Move an object (copy + delete)
`list(options?)`	List objects (paginated)
`listAll(options?)`	List all objects (auto-paginate)
`exists(key)`	Check if an object exists
`getSignedUrl(key, options?)`	Get a signed download URL
`getSignedUploadUrl(key, options?)`	Get a signed upload URL
`upload(key, body, options?)`	Multipart upload for large files

Upload Options

Option	Type	Description
`contentType`	`string`	MIME content type
`cacheControl`	`string`	Cache control header
`metadata`	`Record<string, string>`	Custom metadata
`storageClass`	`string`	Storage class (STANDARD, GLACIER, etc.)
`encryption`	`'AES256' \| 'aws:kms'`	Server-side encryption
`tags`	`Record<string, string>`	Object tags

Signed URL Options

Option	Type	Description
`expiresIn`	`number`	Expiration in seconds (default: 3600)
`responseContentType`	`string`	Override response content type
`responseContentDisposition`	`string`	Override content disposition

Infrastructure Config (Legacy)

Function	Description
`createS3Config(options)`	Create S3 bucket configuration
`buildS3Config(config)`	Build S3 infrastructure config

Constant	Description
`DEFAULT_S3_CONFIG`	Default S3 configuration

Types

Type	Description
`StorageClient`	The storage client interface
`StorageClientConfig`	Client configuration
`PutOptions`	Upload options
`GetResult`	Download result (body + metadata)
`GetStreamResult`	Stream download result
`HeadResult`	Metadata-only result
`ListResult`	List result with pagination
`ObjectInfo`	Object metadata in list results
`SignedUrlOptions`	Signed download URL options
`SignedUploadUrlOptions`	Signed upload URL options
`S3Outputs`	S3 deployment outputs
`S3InfraConfig`	S3 infrastructure configuration