S3Bucket

Lists, uploads, downloads and shares objects in an Amazon S3 bucket.

const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

bucket.downloadFile("imports/budget.csv", "uploads/budget.csv");

Constructor

datasource.S3Bucket datasource.S3Bucket(accessKey, secretKey, bucket, region) S3Bucket

Connects to an S3 bucket and returns an S3Bucket. The connection is checked straight away, so it throws if the credentials are wrong or the bucket doesn't exist.

Parameter	Type	Description
accessKey	string	The AWS access key id.
secretKey	string	The AWS secret access key.
bucket	string	The name of the bucket.
region	string	The bucket's AWS region, for example "ap-southeast-2".

const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

Keep keys out of your scripts

Store the access key and secret key as Secrets and read them with security.getSecret, rather than writing them into the script.

Overview

• Objects and keys: each file in a bucket is an object, identified by its key, such as "exports/2026/actuals.csv". Keys can look like folder paths.
• Listing: list() returns every object in the bucket. For large buckets, or to look inside one "folder", use listPaginiated().
• Sharing: generatePresignedURL() creates a link that anyone can use to download an object until it expires, without AWS credentials.

Methods

list list() array

Returns every object in the bucket. Each object has:

• name: the object's key.
• size: its size in bytes.
• last_modified: when it was last changed, as an ISO timestamp string.

uploadFile uploadFile(objectKey, uploadedFilename)

Uploads a file to the bucket. Throws if the credentials don't allow writing to the bucket.

Parameter	Type	Description
objectKey	string	The key to store the object under.
uploadedFilename	string	The path of the file to upload.

downloadFile downloadFile(objectKey, outputFile)

Downloads an object from the bucket to a file. Throws if the object doesn't exist or the credentials don't allow reading it.

Parameter	Type	Description
objectKey	string	The key of the object to download.
outputFile	string	The path to save it to.

generatePresignedURL generatePresignedURL(objectKey, expiresAfterMinutes) string

Returns a link that downloads an object without AWS credentials until it expires.

Parameter	Type	Description
objectKey	string	The key of the object.
expiresAfterMinutes	number	How many minutes the link works for. The minimum is 1.

close close() optional

Closes the connection to the bucket. The bucket closes automatically when the process finishes, so only call this to close it early.

Examples

Download every file in a folder

const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

const page = bucket.listPaginiated("imports/2026/", 100, 1);

for (const object of page.results) {
    const fileName = object.name.split("/").pop();
    bucket.downloadFile(object.name, "uploads/" + fileName);
}

Upload an export

const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

bucket.uploadFile("exports/2026/actuals.csv", "exports/actuals.csv");

Related

• security.getSecret: reads a stored secret, such as an access key.