nebius/js-sdk

nebius/js-sdk

Language: TypeScript

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2025-08-18T14:26:42Z

Pushed: 2026-06-09T08:56:38Z

Default branch: main

Fork: no

Archived: no

README:

Nebius AI SDK for TypeScript and ECMAScript environments

This repository contains the Nebius SDK for interacting with Nebius AI services from Node.js and other TypeScript and ECMAScript environments.

Quick links

• API reference, generated by TypeDoc
• Generated TypeScript sources from protos: src/api/ (not committed, one has to generate themselves)

Installation

Install from npm (if published):

npm install @nebius/js-sdk

Or, when developing locally from this repository:

git clone git@github.com:nebius/js-sdk.git
cd js-sdk
nvm use
npm install
npm run build

Node.js version

• Build and release automation uses Node.js 24.x (current Active LTS).
• CI verifies the SDK on Node.js 22.x and 24.x, with 25.x kept as a forward-compatibility check.
• If you use nvm, this repository includes .nvmrc; run nvm use before installing dependencies.

When developing inside the repo you can import from the src/ path directly (examples below use local imports for clarity).

Importing (ESM and CJS)

This package publishes dual outputs and an exports map so you can use either syntax:

• ESM:

import { SDK } from '@nebius/js-sdk';

• CommonJS:

const { SDK } = require('@nebius/js-sdk');

Under the hood:

• dist/esm contains the ESM entry facade targeting Node ESM.
• dist/cjs contains the CommonJS build compiled by TypeScript.

How-tos (TypeScript)

This section collects practical how-to recipes. They show common initialization and usage patterns for the TypeScript SDK. For full API details open the TypeDoc pages linked below.

Initialize the SDK

The `SDK` is the base.

Here is the simplest way to initialize it:

import { SDK } from '@nebius/js-sdk';
const sdk = new SDK({});

Initialize using an IAM token from the environment (Static/Env bearer):

import { SDK } from '@nebius/js-sdk';
import { StaticBearer, EnvBearer } from '@nebius/js-sdk/runtime/token/static';

const sdk = new SDK({ credentials: process.env.NEBIUS_IAM_TOKEN });

const sdk = new SDK({ credentials: new StaticBearer(process.env.NEBIUS_IAM_TOKEN) });

const sdk = new SDK({ credentials: new EnvBearer('NEBIUS_IAM_TOKEN') });
// or there are several other ways

Using Config Reader:

import { Config } from '@nebius/js-sdk/runtime/cli_config';
import { SDK } from '@nebius/js-sdk/sdk';

const cfg = new Config({ clientId: 'my-client' });
const sdk = new SDK({ configReader: cfg });

• Using a service account (private key / credentials file):

import { SDK } from '@nebius/js-sdk';

// pass a service account object (id + key) directly
const sdk = new SDK({
serviceAccount: {
serviceAccountId: 'serviceaccount-xxxxx',
publicKeyId: 'public-key-id',
privateKeyPem: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
},
});

or use a credentials file reader

Refer to TypeDoc for all the constructor options: SDK class and Config class.

Test credentials and SDK lifecycle

Use the whoami() helper to validate credentials quickly and sdk.close() to gracefully shutdown.

const { SDK } = require('@nebius/js-sdk');

const sdk = new SDK({
/* ... */
});
const profileReq = sdk.whoami();
const profile = await profileReq;
console.log('Signed-in profile:', profile);

await sdk.close();

Calling services and operations

Generated service clients take the sdk instance as the first parameter. Many RPCs return an `Operation` object — use .result to access a helper that exposes .wait() and .resourceId().

import { SDK } from '@nebius/js-sdk';
import {
BucketService as BucketServiceClient,
CreateBucketRequest,
} from '@nebius/js-sdk/api/nebius/storage/v1/index';

const sdk = new SDK({
/* ... */
});
const bucketSvc = new BucketServiceClient(sdk);

const op = await bucketSvc.create(
CreateBucketRequest.create({
/* ... */
}),
).result;
await op.wait();
console.log('created id=', op.resourceId());

await sdk.close();

Per-request call options (deadlines and per-retry timeouts) can be passed as the request options, including operation's wait().

Progress tracker

Some operations expose a progress tracker with ETA, work completion, and step details. You can access it via `Operation.progressTracker()`. For operations that do not provide progress details (or v1alpha1 operations), this returns undefined.

Example of polling with a single-line progress display:

while (!op.done()) {
await op.update();
const tracker = op.progressTracker();
const parts = [`waiting for operation ${op.id()} to complete:`];

if (tracker) {
const work = tracker.workFraction();
if (work !== undefined) parts.push(`${Math.round(work * 100)}%`);

const desc = tracker.description();
if (desc) parts.push(desc);

const started = tracker.startedAt();
if (started) {
const elapsedMs = Date.now() - started.valueOf();
parts.push(`${Math.round(elapsedMs / 1000)}s`);
}

const eta = tracker.estimatedFinishedAt();
if (eta) parts.push(`eta ${eta.toISOString()}`);
}

process.stdout.write(parts.join(' ') + '\r');
await new Promise((resolve) => setTimeout(resolve, 1000));
}

process.stdout.write('\n');

Parent IDs and resource scoping

Some methods may include parentId in the requests, for certain methods this field is populated automatically:

• Methods list and getByName with an empty parentId
• All other methods, except update, with an empty metadata.parentId

The parentId will only be set if it was preset at the initialization, either from the CLI `Config` or from the parentId attribute from the SDK.

Error handling and request metadata

RPC errors are...