Home /  SFTP / 

SFTP SDK

You can access Stedi SFTP programmatically by creating an SftpClient and using it to send commands. You can use the Stedi SFTP SDK to manage SFTP users. For accessing files programmatically, you should use the Stedi Buckets SDK.

The SDK is available for JavaScript and works with TypeScript.

Installation

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

npm install @stedi/sdk-client-sftp

Commands

CreateUserCommandCreates a new user.
DeleteUserCommandDeletes a user.
ListUsersCommandLists all users.
ReadUserCommandRetrieves information about a user.
UpdateUserCommandUpdates a user’s data.

CreateUserCommand

Creates a new user.

If this is the first time you create a user, a bucket will be created to store all SFTP files. You can access the contents of the bucket using Stedi Buckets.

Parameters

{
  homeDirectory: string,
  description: description,
  passwordOptions: {
    length: number
  }
}

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

  
homeDirectoryRequired. The absolute path to the home directory of the user. The user can access this directory and all its subdirectories, but no other directories. The path must start with a /. It can include letters and numbers, as well as the following characters: -_:.+. You can use / to specify subdirectories. For example, /customers/paper-wrap/shipping.
descriptionRequired. A string that describes the user. You can use it to identify the user, as the username will be generated for you. It can include letters and numbers, as well as the following characters: -_ /.
passwordOptionsOptional. An object that specifies how to generate the user’s password.
passwordOptions.lengthRequired when passwordOptions is provided. The length of the password that will be generated. Minimum: 16. Maximum: 128. Default: 16.

Return value

{
  $metadata: object,
  username: string,
  password: string,
  homeDirectory: string,
  bucketName: string,
  description: string,
  endpoint: string
}

The send() method of the SFTP 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.
userNameThe generated name of the user. You can use this to log into the SFTP server as the user.
passwordThe generated password of the user. You can use this to log into SFTP server as the user. This is the only time the password is returned to you; there’s no way of retrieving it later.
homeDirectoryThe home directory of the user, as specified by you in the command.
bucketNameThe name of the bucket that holds the user’s files. You can use this in combination with the Buckets SDK to access the files programmatically. The bucket name is the same for all users within a Stedi account.
descriptionThe description of the user, as specified by you in the command.
endpointThe endpoint to the SFTP server. When you use an SFTP client to connect to the SFTP server, you can use this value as the address of the host.

Example

import {
  SftpClient,
  CreateUserCommand
} from "@stedi/sdk-client-sftp";

const homeDirectory = "YOUR HOME DIRECTORY HERE";
const description = "YOUR DESCRIPTION HERE";

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

  const createUserCommand = new CreateUserCommand({
    homeDirectory: homeDirectory,
    description: description
  });

  const createUserResult = await sftpClient.send(createUserCommand);
  console.info(createUserResult);
}

main();

DeleteUserCommand

Deletes a user.

This will not delete the files in the user’s home directory. You should use the ListObjectCommand and DeleteObjectCommand in the Buckets SDK if you want to delete the user’s files.

Parameters

{
  username: string
}

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

  
usernameRequired. The name of the user you want to delete. This is the name generated by Stedi SFTP and returned by the CreateUserCommand, not the description of the user you provided.

Return value

{
  $metadata: object
}

The send() method of the SFTP 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.

Example

import {
  SftpClient,
  CreateUserCommand
} from "@stedi/sdk-client-sftp";

const homeDirectory = "YOUR HOME DIRECTORY HERE";
const description = "YOUR DESCRIPTION HERE";

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

  const createUserCommand = new CreateUserCommand({
    homeDirectory: homeDirectory,
    description: description
  });

  const createUserResult = await sftpClient.send(createUserCommand);
  console.info(createUserResult);
}

main();

ListUsersCommand

Retrieve a list of all users.

Parameters

{
  pageSize: number?,
  pageToken: string?
}

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

  
pageSizeOptional. The maximum number of users 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 executed the command.

Return value

{
  "$metadata": object,
  items: [{
    username: string,
    homeDirectory: string,
    description: string,
    bucketName: string,
    endpoint: string,
    lastConnectedDate: string
  }],
  nextPageToken: string?
}

The send() method of the SFTP 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 users.
items.bucketNameThe name of the bucket that holds the user’s files. You can use this in combination with the Buckets SDK to access the files programmatically. The bucket name is the same for all users within a Stedi account.
items.descriptionThe description of the user, as specified when sending the CreateUserCommand.
items.endpointThe endpoint to the SFTP server. When you use an SFTP client to connect to the SFTP server, you can use this value as the address of the host.
items.homeDirectoryThe home directory of the user, as specified when sending the CreateUserCommand.
items.lastConnectedDateThe date the user last connected, e.g. 2022-07-25. undefined if the user has never connected to the SFTP server.
items.userNameThe generated name of the user. You can use this to log into the SFTP server as the user.

Example

import {
  SftpClient,
  ListUsersCommand
} from "@stedi/sdk-client-sftp";

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

  let pageToken = undefined;
  do {
    const listUsersCommand = new ListUsersCommand({
      pageSize: 7,
      pageToken: pageToken
    });

    const listUsersResult = await sftpClient.send(listUsersCommand);
    console.info(listUsersResult.items);

    pageToken = listUsersResult.nextPageToken;
  } while (pageToken !== undefined);
}

main();

ReadUserCommand

Retrieves information about a user.

Parameters

{
  username: string
}

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

  
usernameRequired. The name of the user you want to retrieve. This is the name generated by Stedi SFTP and returned by the CreateUserCommand, not the description of the user you provided.

Return value

{
  $metadata: object,
  bucketName: string,
  description: string,
  endpoint: string,
  homeDirectory: string,
  lastConnectedDate: string,
  userName: string
}

The send() method of the SFTP 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 that holds the user’s files. You can use this in combination with the Buckets SDK to access the files programmatically. The bucket name is the same for all users within a Stedi account.
descriptionThe description of the user, as specified when sending the CreateUserCommand.
endpointThe endpoint to the SFTP server. When you use an SFTP client to connect to the SFTP server, you can use this value as the address of the host.
homeDirectoryThe home directory of the user, as specified when sending the CreateUserCommand.
lastConnectedDateThe date when the user last connected, e.g. 2022-07-25. undefined if the user has never connected to the SFTP server.
userNameThe generated name of the user. You can use this to log into the SFTP server as the user.

Example

import {
  SftpClient,
  ReadUserCommand
} from "@stedi/sdk-client-sftp";

const username = "YOUR USER NAME HERE";

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

  const readUserCommand = new ReadUserCommand({
    username: username
  });
  const readUserResult = await sftpClient.send(readUserCommand);
  console.info(readUserResult);
}

main();

UpdateUserCommand

Updates a user’s data.

Parameters

{
  username: string,
  description: string
}

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

  
usernameRequired. The name of the user you want to update. This is the name generated by Stedi SFTP and returned by the CreateUserCommand.
descriptionRequired. A string that describes the user. You can use it to identify the user. It can include letters and numbers, as well as the following characters: -_ /.

Return value

{
  $metadata: object,
  bucketName: string,
  description: string,
  endpoint: string,
  homeDirectory: string,
  lastConnectedDate: string,
  userName: string
}

The send() method of the SFTP 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 that holds the user’s files. You can use this in combination with the Buckets SDK to access the files programmatically. The bucket name is the same for all users within a Stedi account.
descriptionThe description of the user, as specified in the command.
endpointThe endpoint to the SFTP server. When you use an SFTP client to connect to the SFTP server, you can use this value as the address of the host.
homeDirectoryThe home directory of the user, as specified when sending the CreateUserCommand.
lastConnectedDateThe date the user last connected, e.g. 2022-07-25. undefined if the user has never connected to the SFTP server.
userNameThe generated name of the user. You can use this to log into the SFTP server as the user.

Example

import {
  SftpClient,
  UpdateUserCommand
} from "@stedi/sdk-client-sftp";

const username = "YOUR USER NAME HERE";
const description = "YOUR DESCRIPTION HERE";

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

  const updateUserCommand = new UpdateUserCommand({
    username: username,
    description: description
  });
  const updateUserResult = await sftpClient.send(updateUserCommand);
  console.info(updateUserResult);
}

main();

SftpClient

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 send commands to Stedi SFTP.

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 your SFTP resources. 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 SftpClient class.

Exceptions

Errorregion is missing.

Example

import { SftpClient } from "@stedi/sdk-client-sftp";

const sftpClient = new SftpClient({
  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 { SftpClient } from "@stedi/sdk-client-sftp";

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

sftpClient.destroy();

send

Sends a command to Stedi SFTP.

Parameters

{
  command: Command
}

command must be an instance of one of the valid SFTP 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 { SftpClient } from "@stedi/sdk-client-sftp";

const username = "YOUR USERNAME HERE";

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

  try {
    const readUserCommand = new ReadUserCommand({
      username: username
    });
    const readUserResult = await sftpClient.send(readUserCommand);
    console.info(`Last connected at ${readUserResult.lastConnectedDate}.`);
  }
  catch (error) {
    console.info("The user doesn’t exist.");
  }
}

main();
InstallationCommandsSftpClient