@nebius/js-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nebius B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# 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): [docs/api](docs/api/)
+- Generated TypeScript sources from protos: `src/api/`
+
+## Installation
+
+Install from npm (if published):
+
+```bash
+npm install nebius
+```
+
+Or, when developing locally from this repository:
+
+```bash
+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).
+
+## Importing (ESM and CJS)
+
+This package publishes dual outputs and an exports map so you can use either syntax:
+
+- ESM:
+
+```ts
+import { SDK } from '@nebius/js-sdk';
+```
+
+- CommonJS:
+
+```js
+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`](docs/api/sdk/classes/SDK.md) is the base.
+
+Here is the simplest way to initialize it:
+
+```ts
+import { SDK } from './src/sdk';
+const sdk = new SDK({});
+```
+
+#### Initialize using an IAM token from the environment (Static/Env bearer):
+
+```ts
+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
+```
+
+#### Using Config Reader:
+
+```ts
+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 });
+```
+
+- Using a service account (private key / credentials file):
+
+```ts
+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](docs/api/runtime/service_account/credentials_file/README.md)
+
+Refer to TypeDoc for all the constructor options: [SDK class](docs/api/sdk/classes/SDK.md) and [Config class](docs/api/runtime/cli_config/classes/Config.md).
+
+### Test credentials and SDK lifecycle
+
+Use the `whoami()` helper to validate credentials quickly and `sdk.close()` to gracefully shutdown.
+
+```ts
+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();
+```
+
+### Calling services and operations
+
+Generated service clients take the `sdk` instance as the first parameter. Many RPCs return an [`Operation`](docs/api/runtime/operation/classes/Operation.md) object — use `.result` to access a helper that exposes `.wait()` and `.resourceId()`.
+
+```ts
+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()`.
+
+### 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`](docs/api/runtime/cli_config/classes/Config.md) or from the `parentId` attribute from the [SDK](docs/api/sdk/classes/SDK.md).
+
+### Error handling and request metadata
+
+RPC errors are surfaced as normal thrown errors. The runtime [`Request`](docs/api/runtime/request/classes/Request.md) and [`Operation`](docs/api/runtime/operation/classes/Operation.md) helpers expose metadata and status information, as well as request and trace IDs.
+
+#### Retrieve request id / trace id
+
+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`.
+
+```ts
+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 });
+```
+
+#### Token renewal options
+
+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](docs/api/runtime/token/README.md) and the authorization options interface: [AuthorizationOptions](docs/api/runtime/authorization/provider/interfaces/AuthorizationOptions.md).
+
+Preferred TypeScript pattern — pass `authorizationOptions` in the call options:
+
+```ts
+// 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();
+```
+
+#### Operations service
+
+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:
+
+```ts
+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](docs/api/api/nebius/common/v1/classes/OperationService.md) and the service `getOperationService()` docs (for example: [BucketService](docs/api/api/nebius/storage/v1/classes/BucketService.md)).
+
+### Update / reset-mask helpers
+
+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](docs/api/api/nebius/storage/v1/classes/BucketService.md)) for the exact request shapes and helper methods.
+
+#### Updating with manually set `X-ResetMask`
+
+If 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.
+
+```ts
+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](docs/api/runtime/resetmask/functions/ensureResetMaskInMetadata.md) and [resetMaskFromMessage](docs/api/runtime/resetmask/functions/resetMaskFromMessage.md) for details on how the mask is derived.
+
+### Timeouts, retries and long-running operations
+
+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.
+
+#### Deadlines and timeouts (Node.js)
+
+The SDK applies two layers of timing when making a unary RPC:
+
+- Overall deadline: `deadline` (gRPC CallOptions)
+  - Covers the entire request, including authorization (token acquisition/renewal) and all request retries.
+  - Accepts a JavaScript `Date` or an absolute epoch timestamp in milliseconds (number).
+  - If omitted, the SDK uses a default overall timeout of 15 minutes.
+
+- Authorized request window: `RequestTimeout` (SDK retry option)
+  - Starts after a successful authorization attempt and bounds the inner retry cycle for the actual RPC.
+  - Defaults to 60 seconds when not provided.
+
+- Per-retry timeout: `PerRetryTimeout` (SDK retry option)
+  - Timeout for each individual retry attempt inside the authorized window.
+  - Defaults to `RequestTimeout / RetryCount` when not provided. With defaults (`RequestTimeout = 60s`, `RetryCount = 3`) this is 20 seconds.
+
+- Retry count: `RetryCount` (SDK retry option)
+  - Maximum number of inner retries after a failed attempt (network/transient errors, selected gRPC codes).
+  - Defaults to 3.
+
+Behavior highlights:
+
+- The authorization phase is retried according to the provider’s `canRetry` policy, but is always bounded by the overall `deadline`.
+- After a successful authorization, the SDK runs the actual RPC with internal retries within a single “authorized window” limited by `RequestTimeout` (clipped by the overall `deadline`).
+- Retriable conditions include common transient system errors (e.g., ECONNRESET, ETIMEDOUT) and gRPC status codes `UNAVAILABLE` and `RESOURCE_EXHAUSTED`, as well as SDK and API-specific retry conditions.
+
+Minimal example:
+
+```ts
+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:
+
+- If you provide a numeric `deadline`, it is interpreted as an absolute epoch time in milliseconds.
+- If `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.
+
+### Where to look for types and detailed API
+
+- SDK overview and constructor options: [docs/api/sdk/README.md](docs/api/sdk/README.md) and [SDK class](docs/api/sdk/classes/SDK.md).
+- CLI config reader: [CLI config docs](docs/api/runtime/cli_config/README.md) and [Config class](docs/api/runtime/cli_config/classes/Config.md).
+- Token/bearer implementations: [runtime token docs](docs/api/runtime/token/README.md) and specific classes like `StaticBearer`, `EnvBearer`, `FileBearer`, `ServiceAccountBearer` under `docs/api/runtime/token/`.
+
+If you want runnable examples in the repo, I can add a small `examples/` folder with one or two canonical scripts (auth via token, auth via service account) and ensure they typecheck with the project; tell me if you'd like that.
+
+## API reference / types
+
+Type definitions and the full API reference are generated by TypeDoc and written to `docs/api`.
+
+Useful docs (open the MD files in `docs/api` or browse in GitHub):
+
+- SDK overview: [docs/api/sdk/README.md](docs/api/sdk/README.md) — includes the `SDK` class docs ([SDK class](docs/api/sdk/classes/SDK.md)).
+- CLI-style config reader: [docs/api/runtime/cli_config/README.md](docs/api/runtime/cli_config/README.md) and the `Config` class ([Config class](docs/api/runtime/cli_config/classes/Config.md)).
+- Token and bearer helpers: [docs/api/runtime/token/README.md](docs/api/runtime/token/README.md) and token classes like [StaticBearer](docs/api/runtime/token/static/classes/StaticBearer.md), [EnvBearer](docs/api/runtime/token/static/classes/EnvBearer.md) and [FileBearer](docs/api/runtime/token/file/classes/FileBearer.md).
+
+When editing or consuming the SDK in TypeScript, prefer the generated types in `src/generated/` and the docs in [docs/api](docs/api/).
+
+## Notes & tips
+
+- Generated code in `src/api/` is ignored by the linters. Do not edit generated files by hand.
+- If you need type-level documentation, open [docs/api/index.html](docs/api/index.html) (TypeDoc output) in a browser.
+- For CI and automated docs publishing, the project includes `typedoc` config and build scripts under `package.json`.
+
+### Contributing
+
+Contributions are welcome! Please refer to the [contributing guidelines](CONTRIBUTING.md) for more information.
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2025 Nebius B.V.

package/dist/cjs/__tests__/generator_basic.cases.d.ts

@@ -0,0 +1,2 @@
+export declare function registerSelfCompatTests(): void;
+//# sourceMappingURL=generator_basic.cases.d.ts.map

package/dist/cjs/__tests__/generator_basic.cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator_basic.cases.d.ts","sourceRoot":"","sources":["../../../src/__tests__/generator_basic.cases.ts"],"names":[],"mappings":"AAYA,wBAAgB,uBAAuB,SAumBtC"}