@aezakmiproject/telemt-sdk-nest 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ABRAMOVI4CH
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# @aezakmiproject/telemt-sdk-nest
+
+[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+
+NestJS module for the [Telemt](https://github.com/telemt/telemt) Control API.
+
+Wraps [`@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.
+
+Requires **Node.js 18+** (the SDK uses global `fetch` and `AbortSignal.timeout`).
+
+This project is an independent open-source client. It is not affiliated with Telegram or the Telemt authors.
+
+## Install
+
+```bash
+npm install @aezakmiproject/telemt-sdk-nest
+# or
+pnpm add @aezakmiproject/telemt-sdk-nest
+```
+
+`@nestjs/common` and `@nestjs/core` are expected to be present in the host application.
+
+## Quick start
+
+Register the module once, then inject `TelemtService` anywhere.
+
+```ts
+import { Module } from '@nestjs/common';
+import { TelemtModule } from '@aezakmiproject/telemt-sdk-nest';
+
+@Module({
+  imports: [
+    TelemtModule.forRoot({
+      apiUrl: 'http://127.0.0.1:9091',
+      auth: 'telemt-sdk-dev-token', // exact value of [server.api].auth_header
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { TelemtService } from '@aezakmiproject/telemt-sdk-nest';
+
+@Injectable()
+export class UsersReport {
+  constructor(private readonly telemt: TelemtService) {}
+
+  async listUsernames(): Promise<string[]> {
+    const users = await this.telemt.unwrap(this.telemt.users.getAll());
+    return users.map((user) => user.username);
+  }
+}
+```
+
+`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`.
+
+## Async registration
+
+Use `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.
+
+### useFactory
+
+```ts
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TelemtModule } from '@aezakmiproject/telemt-sdk-nest';
+
+TelemtModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    apiUrl: config.getOrThrow<string>('TELEMT_API_URL'),
+    auth: config.getOrThrow<string>('TELEMT_AUTH'),
+  }),
+});
+```
+
+The factory may be `async`; the client is not constructed until it resolves.
+
+### useClass
+
+```ts
+import { Injectable } from '@nestjs/common';
+import {
+  TelemtModule,
+  type TelemtModuleOptions,
+  type TelemtOptionsFactory,
+} from '@aezakmiproject/telemt-sdk-nest';
+
+@Injectable()
+export class TelemtConfig implements TelemtOptionsFactory {
+  async createTelemtOptions(): Promise<TelemtModuleOptions> {
+    return { apiUrl: process.env.TELEMT_API_URL!, auth: await readSecret() };
+  }
+}
+
+TelemtModule.forRootAsync({ useClass: TelemtConfig });
+```
+
+`useClass` is instantiated by this module, so the class does not need to be provided anywhere else.
+
+### useExisting
+
+Reuse a provider the host application already owns, rather than getting a second instance:
+
+```ts
+TelemtModule.forRootAsync({
+  imports: [TelemtConfigModule], // must export TelemtConfig
+  useExisting: TelemtConfig,
+});
+```
+
+## `TelemtService`
+
+Thin, stateless facade over the underlying `TelemtAPI`. Each getter forwards to the client on every access.
+
+| Member | What it covers |
+| --- | --- |
+| `users` | CRUD, enable/disable, rotate secret, reset quota |
+| `config` | Read / merge-patch `config.toml` |
+| `system` | Build info, reload, `waitForReload` |
+| `health` | Liveness and readiness |
+| `stats` | Counters, upstreams, DCs, ME writers |
+| `runtime` | Gates, ME pool/quality, events, TLS fingerprints |
+| `security` | API posture and IP whitelist |
+| `limits` | Effective timeouts / pool / per-user limits |
+| `client` | The raw `TelemtAPI`, for anything not surfaced above |
+| `unwrap(res)` | Returns `data`, or throws `TelemtApiException` |
+
+The 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).
+
+## Responses and `unwrap`
+
+SDK methods never throw. Every call returns a flat envelope, and transport failures arrive there too, under an `sdk_*` code:
+
+```ts
+interface ISdkResponse<T> {
+  isOk: boolean;
+  data?: T;
+  code?: TelemtErrorCode;
+  message?: string;
+  revision?: string;   // success only — SHA-256 of config.toml
+  requestId?: number;  // Telemt-side errors only
+}
+```
+
+Checking `isOk` by hand keeps that behaviour:
+
+```ts
+const res = await this.telemt.users.getAll();
+if (!res.isOk) {
+  throw new Error(`${res.code}: ${res.message}`);
+}
+// `data` is still `UserInfo[] | undefined` here — see the narrowing note below
+return (res.data ?? []).map((user) => user.username);
+```
+
+`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:
+
+```ts
+const users = await this.telemt.unwrap(this.telemt.users.getAll());
+// users is UserInfo[] — the failure branch has already thrown, and it narrows
+```
+
+It accepts either a response or a promise of one, and on `isOk: false` throws `TelemtApiException`:
+
+```ts
+class TelemtApiException extends Error {
+  readonly code?: string;      // server or `sdk_*` code
+  readonly requestId?: number; // Telemt-side errors only, absent on transport failures
+}
+```
+
+Note that `unwrap` throws whenever `isOk` is false, even if the response also carries partial `data`.
+
+A `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.
+
+## Scope
+
+Each 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.
+
+WEB-proxy session control (`api.web`) is not implemented in the SDK, so it is deliberately not surfaced here.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # vitest, unit tests
+pnpm test:cov    # with V8 coverage
+pnpm typecheck   # tsc, sources + specs
+pnpm build       # tsc -> dist/
+```
+
+Tests 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).
+
+## License
+
+[ISC](LICENSE)

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@aezakmiproject/telemt-sdk-nest",
+  "version": "1.0.0",
+  "description": "NestJS module for the Telemt MTProto proxy Control API: injectable typed client, sync and async registration, no-throw responses, Node 22+",
+  "homepage": "https://github.com/AezakmiProject/telemt-sdk-nest#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AezakmiProject/telemt-sdk-nest.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AezakmiProject/telemt-sdk-nest/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "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": "ABRAMOVI4CH",
+  "license": "ISC",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "devDependencies": {
+    "@aezakmiproject/telemt-sdk": "^1.2.0",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/testing": "^12.0.1",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@aezakmiproject/telemt-sdk": "^1.2.0",
+    "@nestjs/common": "^12.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.spec.json"
+  }
+}