TypeScript SDK

Overview

The StrataGateway TypeScript SDK is intended to provide a typed interface over the StrataGateway REST API, enabling infrastructure automation with first-class TypeScript support.

Planned installation

The SDK is not yet published to npm. The command below illustrates the planned installation method.

npm install @stratagateway/sdk

Important: The final package name and distribution method will be confirmed before public release.

Client setup

Initialize the SDK client with your API token. The example below uses the planned preview syntax.

import { StrataGateway } from "@stratagateway/sdk";

const strata = new StrataGateway({
  token: process.env.STRATA_API_TOKEN,
});

Note: This syntax is illustrative. The final SDK may use a different instantiation pattern. Do not assume the package currently resolves from npm.

Authentication

The SDK is expected to use the same API token authentication model as the REST API.

Set your API token via the STRATA_API_TOKENenvironment variable and pass it to the client.

import { StrataGateway } from "@stratagateway/sdk";

const strata = new StrataGateway({
  token: process.env.STRATA_API_TOKEN,
});

Creating an instance

Provision a new compute instance using the planned instances resource. The example below uses illustrative SDK API syntax.

const instance = await strata.instances.create({
  name: "web-prod-01",
  region: "fra-1",
  plan: "compute-standard",
  image: "ubuntu-24.04-lts",
  sshKeys: ["key_8f3a9b1c"],
});

console.log(instance.id);

Illustrative result

{
  id: "inst_7a91c2",
  name: "web-prod-01",
  status: "provisioning",
  region: "fra-1"
}

Listing instances

List all instances or retrieve a single instance by its identifier.

const instances = await strata.instances.list();

for (const instance of instances.data) {
  console.log(instance.name, instance.status);
}

const instance = await strata.instances.get("inst_7a91c2");

Exact response types are not finalized.

Working with networks

Create and manage private networks using the planned networks resource.

const network = await strata.networks.create({
  name: "production-private",
  region: "fra-1",
  cidr: "10.10.0.0/24",
});

Working with firewalls

Create and manage firewall policies using the planned firewalls resource.

const firewall = await strata.firewalls.create({
  name: "web-production",
  rules: [
    {
      direction: "inbound",
      protocol: "tcp",
      port: "443",
      source: "0.0.0.0/0",
      action: "allow",
    },
  ],
});

SSH keys

Manage SSH keys for instance access using the planned SSH keys resource.

const key = await strata.sshKeys.create({
  name: "Personal Laptop",
  publicKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...",
});

Error handling

Illustrative TypeScript error handling pattern:

try {
  await strata.instances.get("inst_example");
} catch (error) {
  console.error(error);
}

A planned typed error class concept:

class StrataError extends Error {
  code: string;
  message: string;
  requestId: string;
  status: number;

  constructor(code: string, message: string, requestId: string, status: number) {
    super(message);
    this.name = "StrataError";
    this.code = code;
    this.requestId = requestId;
    this.status = status;
  }
}

Possible properties:

The final SDK error hierarchy is still being designed.

Type safety

The SDK is intended to provide comprehensive TypeScript definitions for:

Illustrative type definition:

type InstanceStatus =
  | "provisioning"
  | "running"
  | "stopped"
  | "rebuilding"
  | "deleting"
  | "error";

Async operations

Infrastructure operations such as provisioning, rebuilding, and deleting are expected to be asynchronous. The SDK is planned to return an initial response with a provisioning status.

const instance = await strata.instances.create({...});

console.log(instance.status);
// "provisioning"

Do not assume specific polling intervals or provisioning time guarantees. Final SDK helpers for waiting/polling are still under design.

Environment variables

The SDK is expected to respect the following environment variable:

STRATA_API_TOKEN=your_token_here

Node.js usage:

const token = process.env.STRATA_API_TOKEN;

REST API relationship

The TypeScript SDK is intended to provide typed abstractions over the same platform API used by the REST API, CLI, and other tooling.

TypeScript Application
→ StrataGateway SDK
→ REST API
→ StrataGateway Control Plane

Next steps