@aezakmiproject/telemt-sdk

TypeScript client for the Telemt Control API (/v1).

Typed services over HTTP/1.1 REST: users, config, reload, stats, runtime diagnostics, health, security, and limits. Zero runtime dependencies. Methods never throw — every call returns a flat ISdkResponse<T>.

Requires Node.js 18+ (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

npm install @aezakmiproject/telemt-sdk
# or
pnpm add @aezakmiproject/telemt-sdk

Quick start

import { TelemtAPI } from '@aezakmiproject/telemt-sdk';

const api = new TelemtAPI({
  apiUrl: 'http://127.0.0.1:9091',
  auth: 'telemt-sdk-dev-token', // exact value of [server.api].auth_header
});

const res = await api.users.getAll();
if (!res.isOk) {
  console.error(res.code, res.message);
  return;
}

for (const user of res.data) {
  console.log(user.username, user.in_runtime, user.links.secure);
}

auth is sent verbatim as Authorization. Telemt does constant-time string comparison, not Bearer/OAuth parsing — do not prefix Bearer unless that prefix is literally part of auth_header.

Services

| Property | What it covers | | --- | --- | | api.users | CRUD, enable/disable, rotate secret, reset quota | | api.config | Read / merge-patch config.toml | | api.system | Build info, reload, waitForReload | | api.health | Liveness and readiness | | api.stats | Counters, upstreams, DCs, ME writers | | api.runtime | Gates, ME pool/quality, events, TLS fingerprints | | api.security | API posture and IP whitelist | | api.limits | Effective timeouts / pool / per-user limits |

Full method list, request/response types, and feature gates: docs/api.md.

WEB-proxy session control (api.web) is not implemented yet.

Responses

Every method returns the same shape. Success and transport failure both land here — there is no try/catch around SDK calls.

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
}

A 202 from a user mutation is still isOk: true. The write is on disk; check UserInfo.in_runtime (or call api.system.reload()) before treating the user as live.

Optimistic locking: pass { ifMatch: true } on mutations to send the last seen revision as If-Match.

Details: Client & responses · Error codes

Documentation

| Doc | Contents | | --- | --- | | Getting started | Install, first call, local stand | | Client & responses | Envelope, If-Match, 202 vs 200 | | API reference | Every service method | | Errors | Server and sdk_* codes | | Development | Docker stand, tests, examples | | Integration contract | Wire format, gates, server constraints | | Decisions | Why the types look the way they do |

Runnable scripts live in examples/.

Local Telemt stand

cd docker && docker compose up -d

| | | | --- | --- | | API | http://127.0.0.1:9091 | | Authorization | telemt-sdk-dev-token | | Seeded users | alice, bob, web-user |

Ports bind to 127.0.0.1 only. The API token and user secrets in docker/ are lab fixtures — do not reuse them in production. See Development.

Contributing

See CONTRIBUTING.md. Please follow the Code of Conduct.

Security

See SECURITY.md. Do not file public issues for vulnerabilities.

License

ISC