This repository contains the Nebius SDK for interacting with Nebius AI services from Node.js and other TypeScript and ECMAScript environments.
src/api/ (not committed, one has to generate themselves)Install from npm (if published):
npm install nebius
Or, when developing locally from this repository:
git clone git@github.com:nebius/js-sdk.git
cd js-sdk
npm install
npm run build
When developing inside the repo you can import from the src/ path directly (examples below use local imports for clarity).
This package publishes dual outputs and an exports map so you can use either syntax:
import { SDK } from '@nebius/js-sdk';
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.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.
The SDK is the base.
Here is the simplest way to initialize it:
import { SDK } from './src/sdk';
const sdk = new SDK({});
import { SDK } from './src/sdk';
import { StaticBearer, EnvBearer } from './src/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
import { Config } from './src/runtime/cli_config';
import { SDK } from './src/sdk';
const cfg = new Config({ clientId: 'my-client' });
const sdk = new SDK({ configReader: cfg });
import { SDK } from './src/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.
Use the whoami() helper to validate credentials quickly and sdk.close() to gracefully shutdown.
const { SDK } = require('./src/sdk');
const sdk = new SDK({
/* ... */
});
const profileReq = sdk.whoami();
const profile = await profileReq;
console.log('Signed-in profile:', profile);
await sdk.close();
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 './src/sdk';
import {
BucketService as BucketServiceClient,
CreateBucketRequest,
} from './src/api/nebius/storage/v1';
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().
Some methods may include parentId in the requests, for certain methods this field is populated automatically:
list and getByName with an empty parentIdupdate, with an empty metadata.parentIdThe 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.
RPC errors are surfaced as normal thrown errors. The runtime Request and Operation helpers expose metadata and status information, as well as request and trace IDs.
You can obtain request-level metadata from the returned Request object without awaiting the response immediately. The Request exposes helpers to read requestId and traceId.
const req = bucketSvc.get(GetBucketRequest.create({ id: '...' }));
const response = await req;
const requestId = await req.requestId();
const traceId = await req.traceId();
console.log({ requestId, traceId });
When using renewable bearers (service accounts or other long-lived credentials), the SDK can perform token renewal on-demand for a specific request and surface renewal errors to that call. In TypeScript you express these hints by passing authorizationOptions on the gRPC call options object. See the runtime token docs for general behaviour: runtime token docs and the authorization options interface: AuthorizationOptions.
Preferred TypeScript pattern — pass authorizationOptions in the call options:
// Example: force synchronous renewal and report renewal errors to the request
const callOptions = {
authorizationOptions: {
renewRequired: true,
renewSynchronous: true,
// timeout in milliseconds for the synchronous renewal
renewRequestTimeoutMs: 900,
},
};
// whoami accepts (metadata?, options?) so pass the options directly
await sdk.whoami(undefined, callOptions);
// For normal RPCs provide metadata and callOptions as the second and third args
const md = new (require('@grpc/grpc-js').Metadata)();
const op = await bucketSvc.update(updateReq, md, callOptions);
await op.wait();
Some generated RPCs return an Operation wrapper. To list or fetch operations you should use the getOperationService() helper available on generated service clients (not the standalone OperationServiceClient import). Example:
const svc = new BucketServiceClient(sdk);
const opService = svc.getOperationService();
const listResp = await opService.list({ resourceId: '...' } as any);
// listResp.operations contains OperationWrapper elements; call opService.get(opId) to fetch real Operation
See OperationService and the service getOperationService() docs (for example: BucketService).
When performing partial updates, the generated types and helpers follow the usual pattern: construct an update request and provide update masks where required. See the generated service docs (for example BucketService) for the exact request shapes and helper methods.
X-ResetMaskIf you need to send a partial update that should explicitly reset certain fields to defaults, set the x-resetmask metadata header. The runtime provides helpers to compute and ensure the header is present.
import { ensureResetMaskInMetadata } from './src/runtime/resetmask';
const updateReq = UpdateBucketRequest.create({
metadata: bucket.metadata,
spec: {
/* partial spec */
},
});
const md = ensureResetMaskInMetadata(updateReq);
const op = await bucketSvc.update(updateReq, undefined as any, md);
await op.wait();
See ensureResetMaskInMetadata and resetMaskFromMessage for details on how the mask is derived.
Tune per-call deadlines and per-retry timeouts using call options passed to RPCs. Long-running operations expose .wait(); prefer bounding waits in examples/tests with your own timeout helper to avoid indefinite hangs in CI.
The SDK applies two layers of timing when making a unary RPC:
Overall deadline: deadline (gRPC CallOptions)
Date or an absolute epoch timestamp in milliseconds (number).Authorized request window: RequestTimeout (SDK retry option)
Per-retry timeout: PerRetryTimeout (SDK retry option)
RequestTimeout / RetryCount when not provided. With defaults (RequestTimeout = 60s, RetryCount = 3) this is 20 seconds.Retry count: RetryCount (SDK retry option)
Behavior highlights:
canRetry policy, but is always bounded by the overall deadline.RequestTimeout (clipped by the overall deadline).UNAVAILABLE and RESOURCE_EXHAUSTED, as well as SDK and API-specific retry conditions.Minimal example:
import { Metadata } from '@grpc/grpc-js';
const md = new Metadata();
const options = {
// Overall wall-clock cap (auth + request + retries)
deadline: new Date(Date.now() + 30_000), // 30 seconds, if we know, that we don't need a browser authorization for instance
// Inner retry window after successful authorization
RequestTimeout: 10_000, // 10 seconds
RetryCount: 2, // up to 2 retries
PerRetryTimeout: 5_000, // 5 seconds per attempt (optional; otherwise derives from RequestTimeout/RetryCount)
// Optional: authorization hints (for renewable credentials)
authorizationOptions: {
renewRequired: true,
renewSynchronous: true,
renewRequestTimeoutMs: 900,
},
} as const;
const resp = await bucketSvc.get({ id: '...' } as any, md, options);
Notes:
deadline, it is interpreted as an absolute epoch time in milliseconds.authorizationOptions are set and renewal is needed, renewal will be attempted synchronously within the overall deadline. If renewal cannot succeed before the deadline (or is non-retriable), the SDK returns an UNAUTHENTICATED error.StaticBearer, EnvBearer, FileBearer, ServiceAccountBearer.Type definitions and the full API reference are generated by TypeDoc and written to docs/api. List of all available services.
src/api/ is ignored by the linters. Do not edit generated files by hand.typedoc config and build scripts under package.json.Contributions are welcome! Please refer to the contributing guidelines for more information.
This project is licensed under the MIT License. See the LICENSE file for details.
Copyright (c) 2025 Nebius B.V.