TypeScript SDK
The Steel SDK for TypeScript and JavaScript is the steel-sdk package on npm. It gives your code typed methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The API reference shows the call for each endpoint.
Install
npm install steel-sdkThe SDK supports TypeScript 4.5 or later and these runtimes:
- Node.js 18 LTS or later
- Deno 1.28.0 or later
- Bun 1.0 or later
- Cloudflare Workers and the Vercel Edge Runtime
- Up-to-date web browsers
React Native is not supported. In a web browser, do not give the SDK your API key, because anyone who opens the page can read it. See Authentication.
Create a client
new Steel() reads your API key from the STEEL_API_KEY environment variable. To change the key or another setting, pass options to the constructor.
import Steel from "steel-sdk";
const client = new Steel();| Option | Default | Meaning |
|---|---|---|
steelAPIKey | process. | The API key. The SDK sends it in the steel-api-key header. |
baseURL | process., then https:// | The URL of the API. Change it to use a self-hosted Steel Browser. |
timeout | 60000 | How long one HTTP request can take, in milliseconds. |
maxRetries | 2 | How many times the SDK retries a request that failed. |
defaultHeaders | none | Headers to send with every request. |
defaultQuery | none | Query parameters to send with every request. |
fetch | node-fetch in Node.js, the global fetch elsewhere | A custom fetch function, for example to log each request. |
httpAgent | an agent that reuses connections | The HTTP agent for all requests, for example to send them through a proxy. |
The STEEL_CUSTOM_HEADERS environment variable adds headers to every request. Write one Name: value pair on each line.
Create a session
This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it in finally.
import Steel from "steel-sdk";
const client = new Steel();
const session = await client.sessions.create();
try {
console.log(session.id);
} finally {
await client.sessions.release(session.id);
}Run the program:
npx tsx session.mtsThe program prints the session's ID.
de987dce-13d0-4e2b-b70c-6d2fa9a189d0To drive the session's browser, connect Playwright or Puppeteer over CDP (Chrome DevTools Protocol). See Playwright and Puppeteer.
A method's options are camelCase, such as useProxy and blockAds. In sessions.create, timeout is the session timeout. Session configuration lists every option of a new session.
Retries and timeouts
The SDK retries a request twice, with a short exponential backoff, after one of these failures:
- a connection error
408 Request Timeout409 Conflict429 Too Many Requests- a status of 500 or higher
When the response has the x-should-retry header, the SDK follows the header instead of this list. true retries and false does not. When the response has a Retry-After header, the SDK waits that long before it retries.
A request times out after one minute and then throws APIConnectionTimeoutError. The SDK retries a request that timed out, so a call can take longer than its timeout.
Set maxRetries and timeout on the client for all requests:
const client = new Steel({
maxRetries: 0,
timeout: 20 * 1000,
});To change them for one call, pass them in the method's last argument. This argument holds the request options, not the API's parameters:
await client.sessions.retrieve(session.id, {
maxRetries: 5,
timeout: 5 * 1000,
});Handle errors
When the SDK cannot reach the API, or when the API returns a 4xx or 5xx status, the call throws a subclass of Steel.APIError. The error has status, headers and error, which is the response's JSON body.
try {
await client.sessions.retrieve(sessionId);
} catch (err) {
if (err instanceof Steel.APIError) {
console.log(err.status);
console.log(err.name);
console.log(err.error);
} else {
throw err;
}
}| Status | Error class |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| 500 or higher | InternalServerError |
| No response | APIConnectionError |
Errors lists the error codes and messages of the API.
Pagination
client.sessions.list returns its results in pages. Iterate with for await to read every item. The SDK fetches the next page when it needs it.
for await (const session of client.sessions.list({ status: "live" })) {
console.log(session.id);
}To read one page at a time, use hasNextPage() and getNextPage():
let page = await client.sessions.list({ status: "live" });
while (true) {
for (const session of page.sessions) {
console.log(session.id);
}
if (!page.hasNextPage()) {
break;
}
page = await page.getNextPage();
}Methods
Each group of methods matches a page of the API reference. The methods take the same parameters as the endpoints, in camelCase.
| Methods | API reference |
|---|---|
client., client., client. | Sessions API |
client., client., client. | Quick actions API |
client. | Profiles API |
client. | Credentials API |
client. | Files API |
client. | Extensions API |
client. | Projects API |
client. | API keys API |
The SDK's own list of methods and types is api.md. Your editor also shows the type of each parameter and field, because the package includes TypeScript definitions.