npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@worldlabsai/client

v0.7.0

Published

TypeScript client for the World Labs Developer API

Readme

@worldlabsai/client

Upload images, submit World Labs tasks, and retrieve typed results with the World Labs Developer API client for JavaScript and TypeScript.

Zero runtime dependencies. The client uses the standard Fetch API and ships as ES modules. It supports Node.js 22+ and other Fetch-compatible runtimes. Keep API keys on your server, out of browser bundles.

Install

Install with npm install @worldlabsai/client.

Use a World Labs Developer API key to authenticate API requests.

Before choosing model inputs or combining tasks, read How To Use Atlas.

Usage

The client provides assets for uploads, tasks for submissions, and operations for results. This example combines them to estimate camera poses and depth from a local frame.png, with WLT_API_KEY set on the server:

import { readFile } from "node:fs/promises";
import { assetRef, createClient } from "@worldlabsai/client";

const apiKey = process.env.WLT_API_KEY;
if (!apiKey) throw new Error("Set WLT_API_KEY before running this example");

const wl = createClient({ apiKey });
const image = await wl.assets.upload(await readFile("./frame.png"), {
  displayName: "frame.png",
  mimeType: "image/png",
});
const operation = await wl.tasks.images2PosedRGBD({
  frames: [{ imageAsset: assetRef(image) }],
});
const result = await wl.operations.wait(operation, {
  signal: AbortSignal.timeout(120_000),
});
if (result.error) throw new Error(result.error.message ?? "Task failed");

for (const { camera, depth } of result.response?.frames ?? []) {
  console.log(camera.extrinsics.position, depth.depthAsset.url);
}

assetRef converts an uploaded asset into a task input. Task methods infer the operation's response type, which operations.wait preserves. Other tasks use the same submission and polling pattern.

See examples/ for runnable scripts. posing.ts accepts a local file or a downloadable image URL and documents its environment variables.

Operations and errors

A finished task can still have result.error; check that field before using result.response, as in the example above.

HTTP failures reject with ApiError. Its response.status and body provide the status code and error details. Network failures from JSON API requests reject with NetworkError, with the underlying error in cause. Aborts reject with the signal's reason.

Aborting stops the local request or polling; it does not cancel the server-side task. Keep operation.id to check its status later with operations.get(id). Polling has no default overall timeout. pollIntervalMs sets the pause between incomplete polls and defaults to 1,000 milliseconds.

With { retryNetworkErrors: true }, operations.wait keeps polling the same operation after network failures until it completes or the caller's signal aborts, including a signal with a timeout. Network failures reject by default. It retries HTTP 502, 503, and 504 polling failures up to three times in a row, with pollIntervalMs between attempts. A successful poll resets the retry count. Other failures, including authentication and HTTP 429 rate limits, reject without retrying. Network retries also use pollIntervalMs between attempts.

Task submissions retry network failures and HTTP 429, 502, 503, and 504 up to three times. Every attempt sends the same idempotency key and body. Retries use exponential backoff with jitter and wait at least as long as Retry-After when the server supplies it. A response naming a wait longer than ten seconds, such as a concurrency cap or an hourly quota, rejects at once so you can surface it. Aborting the submission also stops retries. Validation and authentication failures are not retried. Pass { retry: false } to disable submission retries.

If you call the task method again yourself, reuse its idempotencyKey. Each method call otherwise generates a new key. Passing { wait: true } when submitting asks the server to wait up to its own limit; it can still return an unfinished operation.

Client options

Uploads accept bytes or a Blob. Set mimeType for byte arrays or a Blob without a type. Signed storage uploads use the configured fetch but bypass API middleware and API-key authentication.

| Option | Use | | ------------ | --------------------------------------------------------------------------------------------------------------------- | | apiKey | Your Developer API key, or a function that returns a key or a promise of one before each API request. | | baseUrl | API base URL. Defaults to https://api.atlas.worldlabs.ai. | | fetch | Custom Fetch implementation for API requests and uploads. Defaults to globalThis.fetch. | | middleware | Wrap API requests for logging or retries. The first supplied middleware runs outermost, after API-key authentication. | | userAgent | Product tokens that name your app, such as my-app/1.2.0. They are sent before the client's own in User-Agent. |

In Node.js, API requests send User-Agent: worldlabsai-client/<version> node/<version>, after any userAgent tokens. In browsers the browser's own User-Agent is kept.

An empty key or a rejected key provider stops the request before it is sent. Retry middleware must clone a request before sending it so its body can be sent again, and preserve the Idempotency-Key across attempts.

See the Atlas API documentation for API access and usage. JSDoc and TypeScript declarations in the package describe individual methods and options.

License

Copyright 2026 World Labs. Licensed under the Apache License, Version 2.0.