Home /  Functions / 

Functions SDK

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

The SDK is available for JavaScript and works with TypeScript.

If you want to configure bucket notifications that automatically invoke a function, you should use the Stedi Buckets SDK.

Installation

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

npm install @stedi/sdk-client-functions

Commands

CreateFunctionCommandCreate a function.
DeleteFunctionCommandDelete a function.
InvokeFunctionCommandInvoke a function.
ListFunctionsCommandList all functions in your account.
ReadFunctionCommandRetrieve information about a function.
UpdateFunctionCommandReplace a function.

CreateFunctionCommand

Create a function.

Parameters

{
  functionName: string,
  code: string,
  package: Uint8Array,
  environmentVariables: object,
  logRetention: string,
  timeout: number
}

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

functionNameRequired. The name of the function you want to update. The function name must be unique within your account. It may only contain letters, numbers, dashes, and underscores. Maximum length: 64 characters.
codecode and package are mutually exclusive and one of them must be set. The code of the function as a string. Maximum size: 4 KB.
packagecode and package are mutually exclusive and one of them must be set. The code of the function, as a zip package. The zip package must contain a file called index.mjs and that file must export a function called handler. The function should be async. The package may contain a node_modules folder with dependencies, although we recommend bundling all code into a single file. Maximum size: 3 MB.
environmentVariablesOptional. The environment variables that will be passed to the function when it’s invoked. Default: {}.
logRetentionOptional. Indicates how long the function’s logs will be stored. Valid values are: one_day, three_days, five_days, one_week, two_weeks, one_month, two_months, three_months, four_months, five_months, six_months, one_year, thirteen_months, eighteen_months, two_years, five_years, and ten_years. Default: one_day.
timeoutOptional. The maximum number of seconds a single invocation of the function is allowed to last. If the function runs for longer, it will be terminated before it completes. Default: 3. Minimum: 1, Maximum: 900.

Return value

{
  $metadata: object,
  code: string,
  createdAt: string,
  environmentVariables: object,
  functionName: string,
  logRetention: string,
  timeout: number,
  updatedAt: string
}

The send() method of the Functions 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.
codeThe code of the function. This will only be present if you created the code using a string, not a package.
createdAtThe date and time at which the bucket was created, e.g. 2022-11-01T18:34:52.196Z.
environmentVariablesThe environment variables that will be passed to the function when it’s invoked.
functionNameThe name of the function.
logRetentionIndicates how long the function’s logs will be stored.
timeoutThe maximum number of seconds a single invocation of the function is allowed to last. If the function runs for longer, it will be terminated before it completes.
updatedAtThe date and time at which the bucket was last updated, e.g. 2022-11-02T13:40:32.562Z. Since you just created the function, this is the same as createdAt.

Exceptions

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

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

Example

Provide code as a string.

import {
  FunctionsClient,
  CreateFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";
const code =
  "exports.handler = async function(event) {" +
  "  return `It's ${event.username}. ${process.env.GREETING}!`;" +
  "}";

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

  try {
    const createFunctionCommand = new CreateFunctionCommand({
      functionName: functionName,
      code: code,
      logRetention: "three_days",
      timeout: 10,
      environmentVariables: {
        GREETING: "Hello there"
      }
    });
    const createFunctionResult = await functionsClient.send(createFunctionCommand);
    console.info(createFunctionResult);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

Provide code as a package.

import {
  FunctionsClient,
  CreateFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";
import JSZip from "jszip"

const functionName = "YOUR FUNCTION NAME HERE";
const code =
  "export async function handler(event) { " +
  "  return `${process.env.GREETING}, ${event.username}!`;" +
  "}";

async function main() {
  const zip = new JSZip();
  zip.file("index.mjs", code);
  const packagedCode = await zip.generateAsync({
    type: "uint8array",
    compression: "DEFLATE"
  })

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

  try {
    const createFunctionCommand = new CreateFunctionCommand({
      functionName: functionName,
      package: packagedCode,
      logRetention: "three_days",
      timeout: 10,
      environmentVariables: {
        GREETING: "Hello again"
      }
    });
    const createFunctionResult = await functionsClient.send(createFunctionCommand);
    console.info(createFunctionResult);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

DeleteFunctionCommand

Delete a function.

Parameters

{
  functionName: string
}

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

functionNameThe name of the function you want to delete.

Return value

{
  $metadata: object
}

The send() method of the Functions 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 Functions client may raise one of the following exceptions when executing the command.

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

Example

import {
  FunctionsClient,
  DeleteFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";

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

  try {
    const deleteFunctionCommand = new DeleteFunctionCommand({
      functionName: functionName
    });
    await functionsClient.send(deleteFunctionCommand);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

InvokeFunctionCommand

Invoke a function.

Parameters

{
  functionName: string,
  requestPayload: Uint8Array
}

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

functionNameRequired. The name of the function you want to invoke.
requestPayloadOptional. The data you want to send to the function as its event parameter. The payload should be a buffer created from valid JSON. Maximum size: 4 MB.

Return value

{
  $metadata: object,
  functionName: string,
  responsePayload: Uint8Array,
  invocationLogs: string,
  invocationError: string
}

The send() method of the Functions 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.
functionNameThe name of the function. This is the same as the name you specified.
responsePayloadA byte buffer with the return value of the function.
invocationLogsThe first few bytes of the function’s logs, Base64-encoded.
invocationErrorIndicates if the function failed, either due to a runtime error, or because it timed out. "Unhandled" if it did, undefined otherwise.

Exceptions

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

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

Example

import {
  FunctionsClient,
  InvokeFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";
const input = {
  username: "stranger"
};

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

  try {
    const invokeFunctionCommand = new InvokeFunctionCommand({
      functionName: functionName,
      requestPayload: Buffer.from(JSON.stringify(input))
    });
    const invokeFunctionResult = await functionsClient.send(invokeFunctionCommand);

    const responsePayload = Buffer.from(invokeFunctionResult.responsePayload).toString();
    console.info(responsePayload);
    
    const invocationLogs = Buffer.from(invokeFunctionResult.invocationLogs, "base64").toString();
    console.info(invocationLogs);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

ListFunctionsCommand

List all functions in your account.

Parameters

{
  pageSize: number,
  pageToken: string
}

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

pageSizeOptional. The maximum number of functions 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 sent the ListFunctionsCommand.

Return value

{
  $metadata: object,
  items: {
    createdAt: string,
    code: string,
    environmentVariables: object,
    functionName: string,
    logRetention: string,
    timeout: number,
    updatedAt: string
  }
}

The send() method of the Functions 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.
createdAtThe date and time at which the bucket was created, e.g. 2022-11-01T18:34:52.196Z.
environmentVariablesThe environment variables that will be passed to the function when it’s invoked. These are specified when the function is created.
functionNameThe name of the function. This is the same as the name you specified.
logRetentionIndicates how long the function’s logs will be stored.
timeoutThe maximum number of seconds a single invocation of the function is allowed to last. If the function runs for longer, it will be terminated before it completes.
updatedAtThe date and time at which the bucket was last updated, e.g. 2022-11-02T13:40:32.562Z.

Exceptions

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

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

Example

import {
  FunctionsClient,
  ListFunctionsCommand
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";
const input = {
  username: "stranger"
};

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

  let pageToken = undefined;
  do {
    const listFunctionsCommand = new ListFunctionsCommand({
      pageSize: 17,
      pageToken: pageToken
    });
    const listFunctionsResult = await functionsClient.send(listFunctionsCommand);
    console.info(listFunctionsResult.items);

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

main();

ReadFunctionCommand

Retrieve information about a function.

Parameters

{
  functionName: string
}

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

functionNameRequired. The name of the function you want information about.

Return value

{
  $metadata: object,
  code: string,
  createdAt: string,
  environmentVariables: object,
  functionName: string,
  logRetention: string,
  timeout: number,
  updatedAt: string
}

The send() method of the Functions 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.
codeThe code of the function. This will only be present if you created (or updated) the code using a string, not a package.
createdAtThe date and time at which the bucket was created, e.g. 2022-11-01T18:34:52.196Z.
environmentVariablesThe environment variables that will be passed to the function when it’s invoked. These are specified when the function is created.
functionNameThe name of the function. This is the same as the name you specified.
logRetentionIndicates how long the function’s logs will be stored.
timeoutThe maximum number of seconds a single invocation of the function is allowed to last. If the function runs for longer, it will be terminated before it completes.
updatedAtThe date and time at which the bucket was last updated, e.g. 2022-11-02T13:40:32.562Z.

Exceptions

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

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

Example

import {
  FunctionsClient,
  ReadFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";

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

  try {
    const readFunctionCommand = new ReadFunctionCommand({
      functionName: functionName
    });
    const readFunctionResult = await functionsClient.send(readFunctionCommand);
    console.info(readFunctionResult);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

UpdateFunctionCommand

Replace a function.

The function will be completely replaced with the updated settings. The settings you don’t specify will be replaced with their default values.

Parameters

{
  functionName: string,
  code: string,
  package: Uint8Array,
  environmentVariables: object,
  logRetention: string,
  timeout: number
}

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

functionNameRequired. The name of the function you want to update.
codecode and package are mutually exclusive and one of them must be set. The code of the function as a string. This will replace the code the function currently has, regardless of whether that code was previously provided as a string or a package. Maximum size: 4 KB.
packagecode and package are mutually exclusive and one of them must be set. The code of the function, as a zip package. This will replace the code the function currently has, regardless of whether that code was previously provided as a string or a package. The zip package must contain a file called index.mjs and that file must export a function called handler. The function should be async. The package may contain a node_modules folder with dependencies, although we recommend bundling all code into a single file. Maximum size: 3 MB.
environmentVariablesOptional. The environment variables that will be passed to the function when it’s invoked. Default: {}.
logRetentionOptional. Indicates how long the function’s logs will be stored. Valid values are: one_day, three_days, five_days, one_week, two_weeks, one_month, two_months, three_months, four_months, five_months, six_months, one_year, thirteen_months, eighteen_months, two_years, five_years, and ten_years. Default: one_day.
timeoutOptional. The maximum number of seconds a single invocation of the function is allowed to last. If the function runs for longer, it will be terminated before it completes. Default: 3. Minimum: 1, Maximum: 900.

Return value

{
  $metadata: object,
  code: string,
  createdAt: string,
  environmentVariables: object,
  functionName: string,
  logRetention: string,
  timeout: number,
  updatedAt: string
}

The send() method of the Functions 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.
codeThe code of the function. This will only be present if you updated the code using a string, not a package.
createdAtThe date and time at which the bucket was created, e.g. 2022-11-01T18:34:52.196Z.
environmentVariablesThe environment variables that will be passed to the function when it’s invoked. These are specified when the function is created.
functionNameThe name of the function. This is the same as the name you specified.
logRetentionIndicates how long the function’s logs will be stored.
timeoutThe maximum number of seconds a single invocation of the function is allowed to last. If the function runs for longer, it will be terminated before it completes.
updatedAtThe date and time at which the bucket was last updated, e.g. 2022-11-02T13:40:32.562Z.

Exceptions

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

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

Example

Provide code as a string.

import {
  FunctionsClient,
  UpdateFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";
const code =
  "exports.handler = async function(event) {" +
  "  return `${process.env.GREETING}, ${event.username}!`;" +
  "}";

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

  try {
    const updateFunctionCommand = new UpdateFunctionCommand({
      functionName: functionName,
      code: code,
      logRetention: "three_days",
      timeout: 10,
      environmentVariables: {
        GREETING: "Hello there"
      }
    });
    const updateFunctionResult = await functionsClient.send(updateFunctionCommand);
    console.info(updateFunctionResult);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

Provide as a package.

import {
  FunctionsClient,
  UpdateFunctionCommand,
  ValidationException,
  ResourceNotFoundException
} from "@stedi/sdk-client-functions";
import JSZip from "jszip"

const functionName = "YOUR FUNCTION NAME HERE";
const code =
  "export async function handler(event) { " +
  "  return `${process.env.GREETING}, ${event.username}!`;" +
  "}";

async function main() {
  const zip = new JSZip();
  zip.file("index.mjs", code);
  const packagedCode = await zip.generateAsync({
    type: "uint8array",
    compression: "DEFLATE"
  })

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

  try {
    const updateFunctionCommand = new UpdateFunctionCommand({
      functionName: functionName,
      package: packagedCode,
      logRetention: "three_days",
      timeout: 10,
      environmentVariables: {
        GREETING: "Hello again"
      }
    });
    const updateFunctionResult = await functionsClient.send(updateFunctionCommand);
    console.info(updateFunctionResult);
  }
  catch (exception) {
    if (exception instanceof ValidationException) {
      console.info(`${functionName} is not a valid name for a function.`);
    }
    else if (exception instanceof ResourceNotFoundException) {
      console.info(`Function ${functionName} doesn’t exist.`);
    }
    else {
      throw exception;
    }
  }
}

main();

FunctionsClient

constructorCreates a client that allows you to send commands to Stedi Functions.
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 Functions.

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 functions 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 FunctionsClient class.

Exceptions

Errorregion is missing.

Example

import { FunctionsClient } from "@stedi/sdk-client-functions";

const functionsClient = new FunctionsClient({
  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 { FunctionsClient } from "@stedi/sdk-client-functions";

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

functionsClient.destroy();

send

Sends a command to Stedi Functions.

Parameters

{
  command: Command
}

command must be an instance of one of the valid Functions 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 {
  FunctionsClient,
  ReadFunctionCommand
} from "@stedi/sdk-client-functions";

const functionName = "YOUR FUNCTION NAME HERE";

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

  try {
    const readFunctionCommand = new ReadFunctionCommand({
      functionName: functionName
    });
    const readFunctionResult = await functionsClient.send(readFunctionCommand);
    console.info(`The function was created at ${readFunctionResult.createdAt}.`);
  }
  catch (error) {
    console.info("The function doesn’t exist.");
  }
}

main();
InstallationCommandsFunctionsClient