{"_id":"@aezakmiproject/telemt-sdk-nest","_rev":"3-1c689003ef219dcac55e5fb774fda27c","name":"@aezakmiproject/telemt-sdk-nest","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@aezakmiproject/telemt-sdk-nest","version":"1.0.0","keywords":["telemt","telemt-sdk","nestjs","nest","nestjs-module","nestjs-library","nestjs-sdk","mtproto","mtproto-proxy","telegram","telegram-proxy","proxy","proxy-server","typescript","typescript-sdk","sdk","api-client","rest-client","dependency-injection","dynamic-module","node","aezakmi"],"author":{"name":"ABRAMOVI4CH"},"license":"ISC","_id":"@aezakmiproject/telemt-sdk-nest@1.0.0","maintainers":[{"name":"abramovi4ch","email":"winvertg@gmail.com"}],"homepage":"https://github.com/AezakmiProject/telemt-sdk-nest#readme","bugs":{"url":"https://github.com/AezakmiProject/telemt-sdk-nest/issues"},"dist":{"shasum":"8f154e371065f6e17885f0ce7af3e95e1ae62926","tarball":"https://registry.npmjs.org/@aezakmiproject/telemt-sdk-nest/-/telemt-sdk-nest-1.0.0.tgz","fileCount":3,"integrity":"sha512-GRCkJRxk9G1SC8iZNQuO4Vxt1G0zwxvicwZWR3BmcuYKlWtKaYz7fk3nc8Ozdl5TutM/Wk3VwWpmofGd1Cn4oA==","signatures":[{"sig":"MEQCIGGjkGXvTMB9bBAfrWgkztFSU1i55hp44d4s/eZ4KDihAiBkN6dh6LXNGLy6u1QUB7ecmwYNtgqkLMnUKqLBtTp+PQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aezakmiproject%2ftelemt-sdk-nest@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":9435},"main":"dist/index.js","_from":"file:aezakmiproject-telemt-sdk-nest-1.0.0.tgz","types":"dist/index.d.ts","engines":{"node":">=22.12"},"scripts":{"test":"vitest run","build":"tsc","test:cov":"vitest run --coverage","typecheck":"tsc -p tsconfig.spec.json","test:watch":"vitest"},"_npmUser":{"name":"abramovi4ch","email":"winvertg@gmail.com"},"_resolved":"/tmp/bb9f4e24706656f3b4082b54fe142d11/aezakmiproject-telemt-sdk-nest-1.0.0.tgz","_integrity":"sha512-GRCkJRxk9G1SC8iZNQuO4Vxt1G0zwxvicwZWR3BmcuYKlWtKaYz7fk3nc8Ozdl5TutM/Wk3VwWpmofGd1Cn4oA==","repository":{"url":"git+https://github.com/AezakmiProject/telemt-sdk-nest.git","type":"git"},"_npmVersion":"11.19.0","description":"NestJS module for the Telemt MTProto proxy Control API: injectable typed client, sync and async registration, no-throw responses, Node 22+","directories":{},"_nodeVersion":"24.20.0","_hasShrinkwrap":false,"devDependencies":{"rxjs":"^7.8.2","vitest":"^5.0.0","typescript":"^7.0.2","@types/node":"^26.4.1","@nestjs/core":"^12.0.1","@nestjs/common":"^12.0.1","@nestjs/testing":"^12.0.1","reflect-metadata":"^0.2.2","@vitest/coverage-v8":"^5.0.0","@aezakmiproject/telemt-sdk":"^1.2.0"},"peerDependencies":{"@nestjs/common":"^12.0.0","reflect-metadata":"^0.2.0","@aezakmiproject/telemt-sdk":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/telemt-sdk-nest_1.0.0_1788783296018_0.8558791177744245","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aezakmiproject/telemt-sdk-nest","version":"1.1.0","keywords":["telemt","telemt-sdk","nestjs","nest","nestjs-module","nestjs-library","nestjs-sdk","mtproto","mtproto-proxy","telegram","telegram-proxy","proxy","proxy-server","typescript","typescript-sdk","sdk","api-client","rest-client","dependency-injection","dynamic-module","node","aezakmi"],"author":{"name":"ABRAMOVI4CH"},"license":"ISC","_id":"@aezakmiproject/telemt-sdk-nest@1.1.0","maintainers":[{"name":"abramovi4ch","email":"winvertg@gmail.com"}],"homepage":"https://github.com/AezakmiProject/telemt-sdk-nest#readme","bugs":{"url":"https://github.com/AezakmiProject/telemt-sdk-nest/issues"},"dist":{"shasum":"0961cebf15bef95d631e9ed3af5fce9444d462b4","tarball":"https://registry.npmjs.org/@aezakmiproject/telemt-sdk-nest/-/telemt-sdk-nest-1.1.0.tgz","fileCount":3,"integrity":"sha512-Z2WmtNrJjrGArc/KtYB7P7REeWI5PI2uZmwcqhzYdasb5RMAuN+7Sq9FwtuI8puNggJdpcFLk1jgOH9AWlQisA==","signatures":[{"sig":"MEYCIQDDDebPw8nZ0Tiiq1k4EdQzgNk7DeazOudsYrputSQf2AIhAICB+Y20sxxdkf6S3WPC22YhZccnRShH58kmarKd1a+P","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCG2CjZ/W8WvGRzZqgNXhg6oqyJVz7rYGL8PmgHnaO7OQIhAPenoucn+lHmRITc+2kHVSzy2QCmD/yFId/EPWCbhpjK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aezakmiproject%2ftelemt-sdk-nest@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":10157},"main":"dist/index.js","_from":"file:aezakmiproject-telemt-sdk-nest-1.1.0.tgz","types":"dist/index.d.ts","engines":{"node":">=22.12"},"scripts":{"test":"vitest run","build":"tsc","test:cov":"vitest run --coverage","typecheck":"tsc -p tsconfig.spec.json","test:watch":"vitest"},"_npmUser":{"name":"abramovi4ch","email":"winvertg@gmail.com"},"_resolved":"/tmp/bf78f0fb1abafb144da7ce89788f5bf6/aezakmiproject-telemt-sdk-nest-1.1.0.tgz","_integrity":"sha512-Z2WmtNrJjrGArc/KtYB7P7REeWI5PI2uZmwcqhzYdasb5RMAuN+7Sq9FwtuI8puNggJdpcFLk1jgOH9AWlQisA==","repository":{"url":"git+https://github.com/AezakmiProject/telemt-sdk-nest.git","type":"git"},"_npmVersion":"11.19.0","description":"NestJS module for the Telemt MTProto proxy Control API: injectable typed client, sync and async registration, no-throw responses, Node 22+","directories":{},"_nodeVersion":"24.20.0","_hasShrinkwrap":false,"devDependencies":{"rxjs":"^7.8.2","vitest":"^5.0.0","typescript":"^7.0.2","@types/node":"^26.4.1","@nestjs/core":"^12.0.1","@nestjs/common":"^12.0.1","@nestjs/testing":"^12.0.1","reflect-metadata":"^0.2.2","@vitest/coverage-v8":"^5.0.0","@aezakmiproject/telemt-sdk":"^1.2.0"},"peerDependencies":{"@nestjs/common":"^12.0.0","reflect-metadata":"^0.2.0","@aezakmiproject/telemt-sdk":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/telemt-sdk-nest_1.1.0_1788784423849_0.03164030489361358","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"_id":"@aezakmiproject/telemt-sdk-nest@1.1.1","bugs":{"url":"https://github.com/AezakmiProject/telemt-sdk-nest/issues"},"dist":{"shasum":"1dac74cf034703e21611f700ce63e1935bc90803","tarball":"https://registry.npmjs.org/@aezakmiproject/telemt-sdk-nest/-/telemt-sdk-nest-1.1.1.tgz","fileCount":27,"integrity":"sha512-10A9au8BcU43Ki4dQkS3FkWuRNL63+ae05wcZLEy/QaUAQ4Dyt0o6YK1ZneEQipcR8aYyglpF3ucbty1tVgA9Q==","signatures":[{"sig":"MEYCIQCEg6+B7yKpMXqlTL00FwwroLzdmOxjRrAD7O4Jb8sd2wIhAL8QsiKaTvyUxFLkhlbXA0JL4JY4yQX3vcUWGN2ZQ9zQ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDXnIsnQD1CpT6fKMdFxSN05/piDwThUzf6K0EUrCkjFAIhAIB6Ai6O2tBaXUCbi6oAbe3WdqCD0nLrVttL90uoIc6x"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aezakmiproject%2ftelemt-sdk-nest@1.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":27458},"main":"dist/index.js","name":"@aezakmiproject/telemt-sdk-nest","_from":"file:aezakmiproject-telemt-sdk-nest-1.1.1.tgz","types":"dist/index.d.ts","author":{"name":"ABRAMOVI4CH"},"engines":{"node":">=22.12"},"license":"ISC","scripts":{"test":"vitest run","build":"tsc","test:cov":"vitest run --coverage","typecheck":"tsc -p tsconfig.spec.json","test:watch":"vitest"},"version":"1.1.1","_npmUser":{"name":"abramovi4ch","email":"winvertg@gmail.com"},"homepage":"https://github.com/AezakmiProject/telemt-sdk-nest#readme","keywords":["telemt","telemt-sdk","nestjs","nest","nestjs-module","nestjs-library","nestjs-sdk","mtproto","mtproto-proxy","telegram","telegram-proxy","proxy","proxy-server","typescript","typescript-sdk","sdk","api-client","rest-client","dependency-injection","dynamic-module","node","aezakmi"],"_resolved":"/tmp/c8bd05e2ed41c2385f96798c9508befa/aezakmiproject-telemt-sdk-nest-1.1.1.tgz","_integrity":"sha512-10A9au8BcU43Ki4dQkS3FkWuRNL63+ae05wcZLEy/QaUAQ4Dyt0o6YK1ZneEQipcR8aYyglpF3ucbty1tVgA9Q==","repository":{"url":"git+https://github.com/AezakmiProject/telemt-sdk-nest.git","type":"git"},"_npmVersion":"11.19.0","description":"NestJS module for the Telemt MTProto proxy Control API: injectable typed client, sync and async registration, no-throw responses, Node 22+","directories":{},"maintainers":[{"name":"abramovi4ch","email":"winvertg@gmail.com"}],"_nodeVersion":"24.20.0","_hasShrinkwrap":false,"devDependencies":{"rxjs":"^7.8.2","vitest":"^5.0.0","typescript":"^7.0.2","@types/node":"^26.4.1","@nestjs/core":"^12.0.1","@nestjs/common":"^12.0.1","@nestjs/testing":"^12.0.1","reflect-metadata":"^0.2.2","@vitest/coverage-v8":"^5.0.0","@aezakmiproject/telemt-sdk":"^1.2.0"},"peerDependencies":{"@nestjs/common":"^12.0.0","reflect-metadata":"^0.2.0","@aezakmiproject/telemt-sdk":"^1.2.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telemt-sdk-nest_1.1.1_1788880738284_0.4773020511955586"}}},"time":{"created":"2026-09-07T12:14:55.766Z","modified":"2026-09-08T15:18:58.757Z","1.0.0":"2026-09-07T12:14:56.145Z","1.1.0":"2026-09-07T12:33:43.945Z","1.1.1":"2026-09-08T15:18:58.395Z"},"bugs":{"url":"https://github.com/AezakmiProject/telemt-sdk-nest/issues"},"author":{"name":"ABRAMOVI4CH"},"license":"ISC","homepage":"https://github.com/AezakmiProject/telemt-sdk-nest#readme","keywords":["telemt","telemt-sdk","nestjs","nest","nestjs-module","nestjs-library","nestjs-sdk","mtproto","mtproto-proxy","telegram","telegram-proxy","proxy","proxy-server","typescript","typescript-sdk","sdk","api-client","rest-client","dependency-injection","dynamic-module","node","aezakmi"],"repository":{"url":"git+https://github.com/AezakmiProject/telemt-sdk-nest.git","type":"git"},"description":"NestJS module for the Telemt MTProto proxy Control API: injectable typed client, sync and async registration, no-throw responses, Node 22+","maintainers":[{"name":"abramovi4ch","email":"winvertg@gmail.com"}],"readme":"# @aezakmiproject/telemt-sdk-nest\n\n[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)\n\nNestJS module for the [Telemt](https://github.com/telemt/telemt) Control API.\n\nWraps [`@aezakmiproject/telemt-sdk`](https://www.npmjs.com/package/@aezakmiproject/telemt-sdk) in an injectable provider: one configured `TelemtAPI` per registration, resolved through Nest DI, with sync and async registration and an opt-in helper that turns the SDK's no-throw envelope into a thrown exception.\n\nRequires **Node.js 22.12+**. `@nestjs/common` v12 is ESM-only while this package is published as CommonJS, so it relies on `require(esm)`, which is unflagged only from that version.\n\nThis project is an independent open-source client. It is not affiliated with Telegram or the Telemt authors.\n\n## Install\n\nThis package declares its runtime dependencies as peers, so install the SDK alongside it:\n\n```bash\nnpm install @aezakmiproject/telemt-sdk-nest @aezakmiproject/telemt-sdk\n# or\npnpm add @aezakmiproject/telemt-sdk-nest @aezakmiproject/telemt-sdk\n```\n\nThe full peer set is:\n\n| Peer | Range | Notes |\n| --- | --- | --- |\n| `@aezakmiproject/telemt-sdk` | `^1.2.0` | The client this module wraps — install it explicitly |\n| `@nestjs/common` | `^12.0.0` | Already present in any Nest application |\n| `reflect-metadata` | `^0.2.0` | Already present in any Nest application |\n\nKeeping the SDK a peer means your application owns its version, and the module does\nnot pin a second copy of the client into your tree.\n\n## Quick start\n\nRegister the module once, then inject `TelemtService` anywhere.\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { TelemtModule } from '@aezakmiproject/telemt-sdk-nest';\n\n@Module({\n  imports: [\n    TelemtModule.forRoot({\n      apiUrl: 'http://127.0.0.1:9091',\n      auth: 'telemt-sdk-dev-token', // exact value of [server.api].auth_header\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n```ts\nimport { Injectable } from '@nestjs/common';\nimport { TelemtService } from '@aezakmiproject/telemt-sdk-nest';\n\n@Injectable()\nexport class UsersReport {\n  constructor(private readonly telemt: TelemtService) {}\n\n  async listUsernames(): Promise<string[]> {\n    const users = await this.telemt.unwrap(this.telemt.users.getAll());\n    return users.map((user) => user.username);\n  }\n}\n```\n\n`auth` is sent verbatim as the `Authorization` header. Telemt does a constant-time string comparison rather than Bearer/OAuth parsing — do not prefix `Bearer ` unless that prefix is literally part of `auth_header`.\n\n## Async registration\n\nUse `forRootAsync` when the options come from config, a secret store, or anything else resolved at boot. Exactly one of `useFactory`, `useClass`, or `useExisting` is required; passing none throws at module-construction time.\n\n### useFactory\n\n```ts\nimport { ConfigModule, ConfigService } from '@nestjs/config';\nimport { TelemtModule } from '@aezakmiproject/telemt-sdk-nest';\n\nTelemtModule.forRootAsync({\n  imports: [ConfigModule],\n  inject: [ConfigService],\n  useFactory: (config: ConfigService) => ({\n    apiUrl: config.getOrThrow<string>('TELEMT_API_URL'),\n    auth: config.getOrThrow<string>('TELEMT_AUTH'),\n  }),\n});\n```\n\nThe factory may be `async`; the client is not constructed until it resolves.\n\n### useClass\n\n```ts\nimport { Injectable } from '@nestjs/common';\nimport {\n  TelemtModule,\n  type TelemtModuleOptions,\n  type TelemtOptionsFactory,\n} from '@aezakmiproject/telemt-sdk-nest';\n\n@Injectable()\nexport class TelemtConfig implements TelemtOptionsFactory {\n  async createTelemtOptions(): Promise<TelemtModuleOptions> {\n    return { apiUrl: process.env.TELEMT_API_URL!, auth: await readSecret() };\n  }\n}\n\nTelemtModule.forRootAsync({ useClass: TelemtConfig });\n```\n\n`useClass` is instantiated by this module, so the class does not need to be provided anywhere else.\n\n### useExisting\n\nReuse a provider the host application already owns, rather than getting a second instance:\n\n```ts\nTelemtModule.forRootAsync({\n  imports: [TelemtConfigModule], // must export TelemtConfig\n  useExisting: TelemtConfig,\n});\n```\n\n## `TelemtService`\n\nThin, stateless facade over the underlying `TelemtAPI`. Each getter forwards to the client on every access.\n\n| Member | What it covers |\n| --- | --- |\n| `users` | CRUD, enable/disable, rotate secret, reset quota |\n| `config` | Read / merge-patch `config.toml` |\n| `system` | Build info, reload, `waitForReload` |\n| `health` | Liveness and readiness |\n| `stats` | Counters, upstreams, DCs, ME writers |\n| `runtime` | Gates, ME pool/quality, events, TLS fingerprints |\n| `security` | API posture and IP whitelist |\n| `limits` | Effective timeouts / pool / per-user limits |\n| `web` | WEB-proxy session control — **requires Telemt 3.5.1+** |\n| `client` | The raw `TelemtAPI`, for anything not surfaced above |\n| `unwrap(res)` | Returns `data`, or throws `TelemtApiException` |\n\n`web` is version-gated: on a Telemt older than 3.5.1 its calls come back as a failed\n`ISdkResponse` rather than throwing, like every other SDK call.\n\nThe full method list and request/response types live in the [SDK's API reference](https://github.com/AezakmiProject/telemt-sdk/blob/main/docs/api.md).\n\n## Responses and `unwrap`\n\nSDK methods never throw. Every call returns a flat envelope, and transport failures arrive there too, under an `sdk_*` code:\n\n```ts\ninterface ISdkResponse<T> {\n  isOk: boolean;\n  data?: T;\n  code?: TelemtErrorCode;\n  message?: string;\n  revision?: string;   // success only — SHA-256 of config.toml\n  requestId?: number;  // Telemt-side errors only\n}\n```\n\nChecking `isOk` by hand keeps that behaviour:\n\n```ts\nconst res = await this.telemt.users.getAll();\nif (!res.isOk) {\n  throw new Error(`${res.code}: ${res.message}`);\n}\n// `data` is still `UserInfo[] | undefined` here — see the narrowing note below\nreturn (res.data ?? []).map((user) => user.username);\n```\n\n`ISdkResponse` is not a discriminated union, so testing `isOk` does **not** narrow `data`; under `strict` you still have to handle the `undefined`. `unwrap` exists to collapse that:\n\n```ts\nconst users = await this.telemt.unwrap(this.telemt.users.getAll());\n// users is UserInfo[] — the failure branch has already thrown, and it narrows\n```\n\nIt accepts either a response or a promise of one, and on `isOk: false` throws `TelemtApiException`:\n\n```ts\nclass TelemtApiException extends Error {\n  readonly code?: string;      // server or `sdk_*` code\n  readonly requestId?: number; // Telemt-side errors only, absent on transport failures\n}\n```\n\nNote that `unwrap` throws whenever `isOk` is false, even if the response also carries partial `data`.\n\nA `202` from a user mutation is still `isOk: true` — the write is on disk, but check `UserInfo.in_runtime` (or call `system.reload()`) before treating the user as live.\n\n## Scope\n\nEach registration builds its own client, so registering the module in two places gives two independent `TelemtAPI` instances. The module is **not** global: every consuming module must import it, and only `TelemtService` is exported — `TELEMT_CLIENT` and `TELEMT_MODULE_OPTIONS` stay internal to the module.\n\n## Development\n\n```bash\npnpm install\npnpm test        # vitest, unit tests\npnpm test:cov    # with V8 coverage\npnpm typecheck   # tsc, sources + specs\npnpm build       # tsc -> dist/\n```\n\nTests run on [Vitest](https://vitest.dev) rather than Jest because this project pins `typescript@7` (the native compiler), which no longer ships the JS compiler API `ts-jest` needs. See [docs/decisions.md](docs/decisions.md).\n\n## License\n\n[ISC](LICENSE)\n","readmeFilename":"README.md"}