Home /  Buckets / 

Buckets SDK

You can access Stedi Buckets programmatically by creating a BucketsClient-object and using it to send commands.

The SDK is available for JavaScript and works with TypeScript.

Installation

To install the Stedi Buckets SDK, run the following command from your project directory.

npm install @stedi/sdk-client-buckets

Commands

CreateBucketCommandCreates a new bucket.
DeleteBucketCommandDeletes a bucket.
DeleteObjectCommandDeletes an object from a bucket.
GetObjectCommandGets information about the specified object, including a stream for downloading its contents.
ListBucketsCommandLists all buckets.
ListObjectsCommandLists all objects in the specified bucket.
PutObjectCommandUploads an object to the specified bucket using the specified object key.
ReadBucketCommandRetrieves metadata of the specified bucket.

CreateBucketCommand

Creates a new bucket.

Parameters

{
  bucketName: string
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object.

bucketNameRequired. The name of the bucket you want to create. Bucket names must be globally unique. It may only contain lower case letters, numbers, and dashes.

Return value

{
  $metadata: object,
  bucketName: string,
  createdAt: string
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.
bucketNameThe name of the created bucket.
createdAtThe date and time at which the bucket was created, e.g. 2022-07-25T08:48:59.523Z.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

ResourceConflictExceptionA bucket with the name you specified already exists. Bucket names must be globally unique.
ValidationExceptionThe bucket name you specified isn’t valid. The bucket name may only contain lower case letters, numbers, and dashes.

Example

import {
  BucketsClient,
  CreateBucketCommand,
  ValidationException,
  ResourceConflictException
} from "@stedi/sdk-client-buckets";

const bucketName = "YOUR BUCKET NAME HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const createBucketCommand = new CreateBucketCommand({
      bucketName: bucketName
    });
    const createBucketResult = await bucketsClient.send(createBucketCommand);
    console.info(`Created a bucket named ${createBucketResult.bucketName}.`);
  }
  catch (error) {
    if (error instanceof ValidationException) {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error instanceof ResourceConflictException) {
      console.error(`A bucket with the name ${bucketName} already exists.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

DeleteBucketCommand

Deletes a bucket. If you delete a bucket that still has objects in it, all the objects will be deleted as well.

Parameters

{
  bucketName: string
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object.

bucketNameRequired. The name of the bucket you want to delete.

Return value

{
  $metadata: object 
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

InternalFailureExceptionA bucket with the name you specified doesn’t exist in your account.
ValidationExceptionThe bucket name you specified isn’t valid. The bucket name may only contain lower case letters, numbers, and dashes.

Example

import {
  BucketsClient,
  DeleteBucketCommand,
  ResourceNotFoundException,
  ValidationException
} from "@stedi/sdk-client-buckets";

const bucketName = "test-bucket";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const deleteBucketCommand = new DeleteBucketCommand({
      bucketName: bucketName
    });
    await bucketsClient.send(deleteBucketCommand);
    console.info(`Deleted the bucket with the name ${bucketName}.`);
  }
  catch (error) {
    if (error instanceof ResourceNotFoundException) {
      console.error(`${bucketName} is not a bucket in your account.`);
    }
    else if (error instanceof ValidationException) {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

DeleteObjectCommand

Deletes an object from a bucket.

Specifying a key that doesn’t exist is not considered an error, but specifying a bucket that doesn’t exist is.

Parameters

{
  bucketName: string,
  key: string
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object.

bucketNameRequired. The name of the bucket that contains the object you want to delete.
keyRequired. The key of the object you want to delete.

Return value

{
  "$metadata": object 
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

InvalidBucketNameThe bucket name you specified isn’t valid. The bucket name may only contain lower case letters, numbers, and dashes.
InternalFailureExceptionA bucket with the name you specified doesn’t exist in your account.

Example

import {
  BucketsClient,
  DeleteObjectCommand
} from "@stedi/sdk-client-buckets";

const bucketName = "YOUR BUCKET NAME HERE";
const key = "YOUR OBJECT KEY HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const deleteObjectCommand = new DeleteObjectCommand({
      bucketName: bucketName,
      key: key
    });
    await bucketsClient.send(deleteObjectCommand);
    console.info(`Object ${key} deleted from bucket ${bucketName}.`);
  }
  catch (error) {
    if (error.name === "InvalidBucketName") {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error.name === "AccessDenied") {
      console.error(`You don’t have access to bucket ${bucketName}.`);
    }
    else if (error.name === "NoSuchBucket") {
      console.error(`Bucket ${bucketName} doesn’t exist.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

GetObjectCommand

Gets information about the specified object, including a stream for downloading its contents.

Parameters

{
  bucketName: string,
  key: string
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object.

bucketNameRequired. The name of the bucket you want to retrieve the object from.
keyRequired. The key of the object you want to retrieve.

Return value

{
  "$metadata": object,
  body: ReadableStream
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.
bodyA ReadableStream that provides access to the contents of the object.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

InvalidBucketNameThe bucket name you specified isn’t valid. The bucket name may only contain lower case letters, numbers, and dashes.
NoSuchBucketA bucket with the name you specified doesn’t exist in your account.
NoSuchKeyAn object with the key you specified doesn’t exist in the bucket.

Example

import {
  BucketsClient,
  GetObjectCommand
} from  "@stedi/sdk-client-buckets";
import consumers from "stream/consumers";

const bucketName = "YOUR BUCKET NAME HERE";
const key = "YOUR OBJECT KEY HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const getObjectCommand = new GetObjectCommand({
      bucketName: bucketName,
      key: key
    });
    const getObjectResult = await bucketsClient.send(getObjectCommand);
    const contents = await consumers.text(getObjectResult.body);
    console.info(contents);
  }
  catch (error) {
    if (error.name === "InvalidBucketName") {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error.name === "AccessDenied") {
      console.error(`You don’t have access to bucket ${bucketName}.`);
    }
    else if (error.name === "NoSuchBucket") {
      console.error(`Bucket ${bucketName} doesn’t exist.`);
    }
    else if (error.name === "NoSuchKey") {
      console.error(`Object ${key} doesn’t exist.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

ListBucketsCommand

Retrieve a list of all buckets.

Parameters

{
  pageSize: number?,
  pageToken: string?
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object. If you don’t wish to pass arguments to the constructor, you must still provide an empty object.

pageSizeOptional. The maximum number of buckets you want to retrieve. Defaults to 25 and can’t be higher than 50.
pageTokenOptional. A token that allows you to retrieve the next page of results. It should have the same value as the nextPageToken field you received the last time you called listBuckets().

Return value

{
  "$metadata": object,
  items: [{
    bucketName: string,
    createdAt: string
  }],
  nextPageToken: string?
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.
itemsAn array of buckets.
items.bucketNameThe name of the bucket.
items.createdAtThe date and time at which the bucket was created, e.g. 2022-07-25T08:48:59.523Z.
nextPageTokenA token that allows you to retrieve the next page of result. The next time you call listBuckets(), set pageToken to this value to retrieve additional results. If there are no more results, nextPageToken will be undefined.

Exceptions

None.

Example

import {
  BucketsClient,
  ListBucketsCommand
} from "@stedi/sdk-client-buckets";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    let pageToken = undefined;
    do {
      const listBucketsCommand = new ListBucketsCommand({
        pageSize: 7,
        pageToken: pageToken
      });
      const listBucketsResult = await bucketsClient.send(listBucketsCommand);
      console.info(listBucketsResult.items);

      pageToken = listBucketsResult.nextPageToken;
    } while (pageToken !== undefined);
  }
  catch (error) {
    console.error(error);
  }
}

main();

ListObjectsCommand

Retrieve a list of all objects in the specified bucket.

Parameters

{
  bucketName: string,
  pageSize: number?,
  pageToken: string?
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object.

bucketNameRequired. The name of the bucket whose objects you want to list.
pageSizeOptional. The maximum number of buckets you want to receive. Defaults to 25 and can’t be higher than 50.
pageTokenOptional. A token that allows you to retrieve the next page of results. It should have the same value as the nextPageToken field you received the last time you called listObjects().

Return value

{
  "$metadata": object,
  items: [{
    key: string,
    size: number
  }],
  nextPageToken: string?
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.
itemsAn array of objects.
items.keyThe key of the object.
items.sizeThe size of the object in bytes.
nextPageTokenA token that allows you to retrieve the next page of result. The next time you call listObjects(), set pageToken to this value to retrieve additional results. If there are no more results, nextPageToken will be undefined.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

ValidationExceptionThe bucket name you specified isn’t valid. The bucket name may only contain lower case letters, numbers, and dashes.
InternalFailureExceptionA bucket with the name you specified doesn’t exist in your account.

Example

import {
  BucketsClient,
  ListObjectsCommand
} from "@stedi/sdk-client-buckets";

const bucketName = "YOUR BUCKET NAME HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    let pageToken = undefined;
    do {
      const listObjectsCommand = new ListObjectsCommand({
        bucketName: bucketName,
        pageSize: 7,
        pageToken: pageToken
      });

      const listObjectsResult = await bucketsClient.send(listObjectsCommand);
      console.info(listObjectsResult.items);

      pageToken = listObjectsResult.nextPageToken;
    } while (pageToken !== undefined);
  }
  catch (error) {
    if (error.name === "InvalidBucketName") {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error.name === "AccessDenied") {
      console.error(`${bucketName} is not a bucket in your account.`);
    }
    else if (error.name === "NoSuchBucket") {
      console.error(`Bucket ${bucketName} doesn’t exist.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

PutObjectCommand

Uploads an object to the specified bucket using the specified object key.

If you specify a key that doesn’t exist yet, an object with that key will be created. If the key already exists, the object will be replaced.

Parameters

{
  bucketName: string,
  key: string,
  body: ReadableStream | string
}

The constructor takes an object as its only argument. All parameters are fields within this object.

bucketNameRequired. The name of the bucket you want to upload an object to.
keyRequired. The key of the object you want to upload.
bodyRequired. A ReadableStream that provides access to the contents you want to upload, or a string with the contents.

Return value

{
  $metadata: object,
  body: ReadableStream
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

InvalidBucketNameThe bucket name you specified isn’t valid. The bucket name may only contain lower case
NoSuchBucketA bucket with the name you specified doesn’t exist in your account.

Example

Store a string.

import {
  BucketsClient,
  PutObjectCommand
} from "@stedi/sdk-client-buckets";

const bucketName = "YOUR BUCKET NAME HERE";
const key = "YOUR OBJECT KEY HERE";
const contents = "YOUR OBJECT CONTENTS HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const putObjectCommand = new PutObjectCommand({
      bucketName: bucketName,
      key: key,
      body: contents
    });
    await bucketsClient.send(putObjectCommand);
  }
  catch (error) {
    if (error.name === "InvalidBucketName") {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error.name === "AccessDenied") {
      console.error(`${bucketName} is not a bucket in your account.`);
    }
    else if (error.name === "NoSuchBucket") {
      console.error(`Bucket ${bucketName} doesn’t exist.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

Store the contents of a local file.

import {
  BucketsClient,
  PutObjectCommand
} from "@stedi/sdk-client-buckets";
import { createReadStream } from "fs";

const bucketName = "YOUR BUCKET NAME HERE";
const key = "YOUR OBJECT KEY HERE";
const fileName = "YOUR LOCAL FILE NAME HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const putObjectCommand = new PutObjectCommand({
      bucketName: bucketName,
      key: key,
      body: createReadStream(fileName)
    });
    await bucketsClient.send(putObjectCommand);
  }
  catch (error) {
    if (error.name === "InvalidBucketName") {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error.name === "AccessDenied") {
      console.error(`${bucketName} is not a bucket in your account.`);
    }
    else if (error.name === "NoSuchBucket") {
      console.error(`Bucket ${bucketName} doesn’t exist.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

ReadBucketCommand

Retrieves the metadata of the specified bucket.

Parameters

{
  bucketName: string
}

The constructor of the command takes an object as its only arguments. All parameters are fields within this object.

bucketNameRequired. The name of the bucket you want to retrieve.

Return value

{
  $metadata: object,
  bucketName: string,
  createdAt: string
}

The send() method of the Buckets client will return the result of the command.

$metadataAn object containing data about the request the client made to the backend. The fields in this object are subject to change and you shouldn’t rely on them.
bucketNameThe name of the bucket.
createdAtThe date and time at which the bucket was created, e.g. 2022-07-25T08:48:59.523Z.

Exceptions

The send() method of the Buckets client may raise one of the following exceptions when executing the command.

ValidationExceptionThe bucket name you specified isn’t valid. The bucket name may only contain lower case letters, numbers, and dashes.
ResourceNotFoundExceptionA bucket with the name you specified doesn’t exist in your account.

Example

import {
  BucketsClient,
  ReadBucketCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-buckets";

const bucketName = "YOUR BUCKET NAME HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const readBucketCommand = new ReadBucketCommand({
      bucketName: bucketName
    });
    const readBucketResult = await bucketsClient.send(readBucketCommand);
    console.info(`Bucket ${readBucketResult.bucketName} was created at ${readBucketResult.createdAt}.`);
  }
  catch (error) {
    if (error instanceof ValidationException) {
      console.error(`${bucketName} is not a valid name for a bucket.`);
    }
    else if (error instanceof ResourceNotFoundException) {
      console.error(`Bucket ${bucketName} doesn’t exist.`);
    }
    else {
      console.error(error);
    }
  }
}

main();

BucketsClient

constructorCreates a client that allows you to send commands to Stedi Buckets.
destroy()Shuts down the client and its underlying resources.
send()Sends a command.

constructor

Creates a client that allows you to call functions on Stedi Buckets.

Parameters

{
  region: string,
  apiKey: string
}

The constructor takes an object as its only argument. All parameters are fields within this object.

regionRequired. The region that hosts the buckets you want to connect to. At the moment, we only support us.
apiKeyRequired. The API key used to authenticate your requests. You can create a client without specifying apiKey, but if you do, calls to send() will fail.

Return value

An instance of the BucketsClient class.

Exceptions

Errorregion is missing.

Example

import { BucketsClient } from "@stedi/sdk-client-buckets";

const bucketsClient = new BucketsClient({
  region: "us",
  apiKey: process.env.STEDI_API_KEY
});

destroy

Shuts down the client and its underlying resources.

The client shuts down automatically when it’s garbage collected, but in a long-running process, it’s best to explicitly shut it down when it’s no longer needed.

Return value

None.

Exceptions

None.

Example

import { BucketsClient } from "@stedi/sdk-client-buckets";

const bucketsClient = new BucketsClient({
  region: "us",
  apiKey: process.env.STEDI_API_KEY
});

bucketsClient.destroy();

send

Sends a command to Stedi Buckets.

Parameters

{
  command: Command
}

command must be an instance of one of the valid Buckets commands.

Return value

Depends on the command you sent. Check the description of the command you’re interested in.

Exceptions

Depends on the command you sent. Check the description of the command you’re interested in.

Example

import {
  BucketsClient,
  ReadBucketCommand
} from "@stedi/sdk-client-buckets";

const bucketName = "YOUR BUCKET NAME HERE";

async function main() {
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  try {
    const readBucketCommand = new ReadBucketCommand({
      bucketName: bucketName
    });
    const readBucketResult = await bucketsClient.send(readBucketCommand);
    console.info(`The bucket was created at ${readBucketResult.createdAt}.`);
  }
  catch (error) {
    console.info("The bucket doesn’t exist.");
  }
}

main();
InstallationCommandsBucketsClient