Overview

FluidStack’s TypeScript SDK assists in developing applications in TypeScript using the FluidStack API.

It includes the following features:

• TypeScript interfaces for all request and response types
• Exception handling as subclasses of FluidStackApiError
• Ability to abort requests
• Runtime compatibility
• Ability to customize the fetch client
• Automatic retries with exponential backoff
• Configurable timeouts

Request and response types

The SDK exports all request and response types as TypeScript interfaces. Import them with the following namespace:

1
import { FluidStackApi } from "fluidstack";
2

3
const request: FluidStackApi.CreateInstanceRequest = {
4
    ...
5
};
6
const response = await fluidStackApi.create(request);

Exception handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of FluidStackApiError is thrown.

1
import { FluidStackApiError } from 'fluidstack';
2

3
try {
4
    await fluidStackApi.create(...);
5
} catch (err) {
6
    if (err instanceof FluidStackApiError) {
7
        console.log(err.statusCode);
8
        console.log(err.message);
9
        console.log(err.body);
10
    }
11
}

Abort requests

Abort requests at any point by passing in an abort signal.

1
const controller = new AbortController();
2
const response = await fluidStackApi.create(..., {
3
    abortSignal: controller.signal
4
});
5
controller.abort(); // aborts the request

Runtime compatibility

The SDK defaults to node-fetch but will use the global fetch client if present.

The SDK works in the following runtimes:

• Node.js 18+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Customize the fetch client

The SDK provides a way for your to customize the underlying HTTP client or fetch function. If you’re running in an unsupported environment, this provides a way for you to break the glass and ensure that the SDK works.

1
import { FluidStackApiClient } from 'fluidstack';
2

3
const fluidStackApi = new FluidStackApiClient({
4
    ...
5
    fetcher: // provide your implementation here
6
});

Advanced

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retriable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retriable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

1
const response = await fluidStackApi.create(..., {
2
    maxRetries: 0 // override maxRetries at the request level
3
});

Timeouts

The SDK defaults to a 60-second timeout. Use the timeoutInSeconds option to configure this behavior.

1
const response = await fluidStackApi.create(..., {
2
    timeoutInSeconds: 30 // override timeout to 30s
3
});