Merge pull request #206 from yandex-cloud/beta

Stable 3.0

Author: DavyJohnes

.commitlintrc.json

@@ -1,5 +1,3 @@
 {
-  "extends": [
-    "@commitlint/config-conventional"
-  ]
+  "extends": ["@commitlint/config-conventional"]
 }

.eslintignore

@@ -1 +1,2 @@
 src/generated/**
+src/clients/**

.eslintrc.json

@@ -11,12 +11,7 @@
     "plugin:@typescript-eslint/recommended"
   ],
   "parser": "@typescript-eslint/parser",
-  "plugins": [
-    "@typescript-eslint",
-    "unicorn",
-    "import",
-    "prefer-arrow-functions"
-  ],
+  "plugins": ["@typescript-eslint", "unicorn", "import", "prefer-arrow-functions"],
   "parserOptions": {
     "project": "tsconfig.eslint.json"
   },
@@ -31,8 +26,8 @@
     "import/prefer-default-export": "off",
     "comma-dangle": ["error", "always-multiline"],
     "indent": "off",
-    "@typescript-eslint/indent": ["error", 4],
     "max-len": ["error", 140],
+    "@typescript-eslint/indent": ["error", 4],
     "@typescript-eslint/ban-ts-comment": "off",
     "@typescript-eslint/prefer-optional-chain": "error",
     "prefer-arrow-functions/prefer-arrow-functions": ["error"],
@@ -42,14 +37,21 @@
     "no-plusplus": "off",
     "unicorn/import-style": "off",
     "@typescript-eslint/no-var-requires": "off",
-    "no-underscore-dangle": ["error", {
-      "allowAfterThis": true,
-      "allowAfterSuper": false
-    }],
+    "no-underscore-dangle": [
+      "error",
+      {
+        "allowAfterThis": true,
+        "allowAfterSuper": false
+      }
+    ],
     "unicorn/no-null": "off",
-    "import/no-extraneous-dependencies": ["error", {
-      "devDependencies": true
-    }],
-    "import/no-cycle": "off"
+    "import/no-extraneous-dependencies": [
+      "error",
+      {
+        "devDependencies": true
+      }
+    ],
+    "import/no-cycle": "off",
+    "@typescript-eslint/no-explicit-any": 1
   }
 }

.github/actions/checkout-and-install-node/action.yml

@@ -5,6 +5,10 @@ inputs:
     description: 'Whether to configure the token or SSH key with the local git config'
     required: false
     default: 'true'
+  submodules:
+    description: 'Whether to checkout submodules along with specified repo'
+    required: false
+    default: 'false'
 runs:
   using: 'composite'
   steps:

.github/workflows/pr-checks.yml

@@ -9,25 +9,27 @@ jobs:
   tests:
     runs-on: ubuntu-24.04
     steps:
-      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@d6b5322d8dbc130126ec1fa00bc0f2d6cc2f53db
+      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@7992e39cce119c931dab92f6879013efff123009
+        with:
+          submodules: recursive
       - run: npm run test
   check-endpoints:
     runs-on: ubuntu-24.04
     # Currently, the check-endpoints script fails on the master branch.
     # So we need to continue on error.
     continue-on-error: true
     steps:
-      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@d6b5322d8dbc130126ec1fa00bc0f2d6cc2f53db
+      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@7992e39cce119c931dab92f6879013efff123009
         with:
           submodules: recursive
       - run: npm run check-endpoints
   lint:
     runs-on: ubuntu-24.04
     steps:
-      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@d6b5322d8dbc130126ec1fa00bc0f2d6cc2f53db
+      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@7992e39cce119c931dab92f6879013efff123009
       - run: npm run lint
   build:
     runs-on: ubuntu-24.04
     steps:
-      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@d6b5322d8dbc130126ec1fa00bc0f2d6cc2f53db
+      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@7992e39cce119c931dab92f6879013efff123009
       - run: npm run build

.github/workflows/release.yml

@@ -11,7 +11,7 @@ jobs:
     name: Release
     runs-on: ubuntu-24.04
     steps:
-      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@d6b5322d8dbc130126ec1fa00bc0f2d6cc2f53db
+      - uses: yandex-cloud/nodejs-sdk/.github/actions/checkout-and-install-node@7992e39cce119c931dab92f6879013efff123009
         with:
           persist-credentials: false
       - env:

.gitignore

@@ -1,3 +1,5 @@
 .idea
 node_modules
 dist
+.env
+.vscode

.prettierignore

@@ -0,0 +1 @@
+**/generated/**

.prettierrc.js

@@ -0,0 +1,21 @@
+module.exports = {
+    tabWidth: 4,
+    printWidth: 100,
+    singleQuote: true,
+    trailingComma: 'all',
+    bracketSpacing: true,
+    overrides: [
+        {
+            files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
+            options: {
+                parser: 'typescript',
+            },
+        },
+        {
+            files: ['*.md', '*.json', '*.yaml', '*.yml'],
+            options: {
+                tabWidth: 2,
+            },
+        },
+    ],
+};

CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Yandex Cloud Node.js SDK (`@yandex-cloud/nodejs-sdk`). Provides typed gRPC clients for all Yandex Cloud services, generated from protobuf definitions in the `cloudapi` git submodule.
+
+## Commands
+
+- **Build:** `npm run build` (compiles TypeScript to `dist/`)
+- **Lint:** `npm run lint` (ESLint on `src` and `config`)
+- **Test:** `npm test` (runs Jest; auto-generates services first)
+- **Single test:** `cross-env NODE_OPTIONS="--max-old-space-size=8192" node --experimental-vm-modules node_modules/jest/bin/jest.js -c config/jest.ts --passWithNoTests 'path/to/test'`
+- **Typecheck:** `npm run typecheck` (checks both src and examples)
+- **Generate services from protos:** `npm run cloudapi:generate-services`
+- **Update cloudapi submodule:** `npm run cloudapi:update`
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint via husky hook). Semantic-release publishes from `master`, `beta`, and `alpha` branches.
+
+## Architecture
+
+### Code generation pipeline
+
+The `cloudapi` submodule contains `.proto` files from `github.com/yandex-cloud/cloudapi`. The `scripts/generate_services` script:
+1. Runs `ts-proto` via `grpc_tools_node_protoc` to generate TypeScript types/clients into `src/generated/`
+2. Detects service directories and creates re-export `index.ts` files in `src/clients/<service-name>/`
+3. Updates `package.json` exports map so each service is importable as `@yandex-cloud/nodejs-sdk/<service-name>`
+
+**Do not edit files in `src/generated/` or `src/clients/*/index.ts` manually** — they are overwritten by code generation. Client directories may contain an `export-alias.json` for custom export names.
+
+### Session and client creation
+
+`Session` (`src/session.ts`) is the main entry point. It handles authentication (OAuth, IAM token, service account JSON, or metadata service) and creates gRPC channels with credentials. Clients are obtained via `session.client(ServiceClient)`, which resolves endpoints from `src/service-endpoints-map.json`.
+
+### Middleware stack
+
+The client factory (`src/utils/client-factory.ts`) chains three `nice-grpc` middlewares:
+1. **errorMetadataMiddleware** — wraps errors into `ApiError` with request/trace IDs from gRPC metadata
+2. **retryMiddleware** — exponential backoff retry for idempotent/configured calls
+3. **deadlineMiddleware** — from `nice-grpc-client-middleware-deadline`
+
+### Service endpoint resolution
+
+`src/service-endpoints.ts` maps a gRPC service's `serviceName` to its API endpoint using `src/service-endpoints-map.json`. The map is updated by the generation script via `scripts/check-endpoints.ts` which queries `https://api.cloud.yandex.net/endpoints`.
+
+### Key types
+
+- `SessionConfig` — union of credential configs (OAuth, IAM token, service account, generic/metadata)
+- `WrappedServiceClientType<S>` — nice-grpc `RawClient` with retry + deadline call options
+- `ClientCallArgs` — `RetryOptions & DeadlineOptions`, passed per-call
+- `ApiError` — extends `Error` with gRPC metadata (`requestId`, `serverTraceId`)