All Symbols - @hertzg/tplink-api documentation

mod.ts

TP-Link Router API client library for Deno.

Examples

Basic authentication and command execution

import { ACT, authenticate, execute } from "@hertzg/tplink-api";

const auth = await authenticate("http://192.168.1.1", {
  password: "admin",
});

if (auth) {
  const result = await execute(
    "http://192.168.1.1",
    [[ACT.GET, "LTE_BANDINFO"]],
    auth,
  );
  // result.error === 0 indicates success
  // result.actions[0].res contains the response data
}

Get unread SMS count with specific attributes

import { ACT, type Action } from "@hertzg/tplink-api";

const actions: Action[] = [
  [ACT.GET, "LTE_SMS_UNREADMSGBOX", ["totalNumber"]],
];

Retrieve SMS messages with pagination

import { ACT, type Action } from "@hertzg/tplink-api";

const actions: Action[] = [
  [ACT.SET, "LTE_SMS_UNREADMSGBOX", { pageNumber: "1" }],
  [ACT.GS, "LTE_SMS_UNREADMSGENTRY", ["index", "from", "content", "receivedTime"]],
];

Functions

authenticate(

baseUrl: string,

options: AuthOptions

): Promise<AuthResult | null>

Authenticates with a TP-Link router and returns session context.

execute(

baseUrl: string,

actions: Action[],

options: ExecuteOptions

): Promise<ExecuteResult>

Executes one or more actions on the router.

Interfaces

ActionResult

Result of a single action execution, mapping request to response.

req: Action
Original action that was requested
res: Record<string, string> | Record<string, string>[] | null
Response data: single object, array of objects, or null if no data

AuthOptions

Options for authenticating with the router.

dialect: Dialect
Firmware dialect to speak (defaults to gdprText)
fetch: globalThis.fetch
Swappable fetch, for tests or non-standard HTTP stacks
forceLogin: boolean
Force re-authentication even if already logged in (defaults to true)
password: string
Password for authentication
username: string
Username for authentication (defaults to the dialect's default username)

AuthResult

Result of successful authentication containing all data needed for API calls.

dialect: Dialect
Dialect used, carried forward so execute needs no extra argument
encryption: Encryption
Encryption instance for encrypting/decrypting API payloads
info: RouterInfo
Router information retrieved during authentication
sequence: number
Sequence number for request signing
sessionId: string
Session ID cookie value
tokenId: string
Security token for API requests

BusyStatus

isBusy: boolean
Whether the router is busy serving another management session.
isLoggedIn: boolean
Whether a session is already established from another client.

CommandBatch

One HTTP round trip's worth of actions.

indices: readonly number[]
Indices into the caller's actions array, in the order the response returns them.
payload: string
Plaintext payload for this round trip, pre-encryption.

Credentials

Credentials as supplied by the caller, after the dialect's username default has been applied.

password: string
Account password, verbatim.
username: string
Account name, defaulted from Dialect.defaultUsername.

DecodedBatch

Decoded result of one round trip, positionally aligned with CommandBatch.indices.

error: number | null
Router error code, or null when the batch reported no error.
results: readonly (Record<string, string> | Record<string, string>[] | null)[]
One entry per index in the batch; null where the router returned nothing.

Dialect

A firmware family's wire protocol, expressed as pure functions and data.

busyRequest(baseUrl: string): Request
Builds the request that reports whether a session is already established.
commandRequest(
baseUrl: string,
envelope: Envelope,
session: SessionContext
): Request
Builds a command request for one batch's envelope.
decodeCommand(
text: string,
batch: CommandBatch
): DecodedBatch
Decodes a decrypted command response into results aligned with the batch.
defaultUsername: string
Username used when the caller supplies none.
encodeCommands(actions: readonly Action[]): readonly CommandBatch[]
Splits actions into round trips and serializes each. Owns the operation vocabulary, stack defaults, and batching.
encodeLogin(credentials: Credentials): string
Encodes credentials into the plaintext login payload, pre-encryption.
id: string
Stable identifier, carried on the authentication result for diagnostics.
infoRequest(baseUrl: string): Request
Builds the request for the login page, whose inline script carries authTimes and friends.
loginRequest(
baseUrl: string,
envelope: Envelope
): Request
Builds the login request. Owns where the envelope rides — query string, request body, or anywhere else the firmware expects it.
parseBusy(text: string): BusyStatus
Extracts login and busy flags from the busy response.
parseInfo(html: string): RouterInfo
Scrapes router variables out of the login page.
parsePublicKey(text: string): PublicKeyInfo
Extracts RSA parameters from the public key response.
parseSessionId(headers: Headers): string | null
Extracts the session id from the login response headers.
parseTokenId(html: string): string
Extracts the security token from the authenticated page.
publicKeyRequest(baseUrl: string): Request
Builds the request for the RSA public key and sequence base.
tokenRequest(
baseUrl: string,
session: Pick<SessionContext, "sessionId" | "authTimes">
): Request
Builds the request for the authenticated page carrying the security token.

Envelope

Encrypted request envelope: AES ciphertext plus the RSA-encrypted signature.

data: string
Base64 AES-CBC ciphertext of the plaintext payload.
sign: string
Hex RSA-encrypted parameter string: key&iv&h&s for login, h&s for commands.

ExecuteOptions

Options required for executing commands on the router. These values are obtained from authenticate.

authTimes: number
Authentication times counter (defaults to 1)
dialect: Dialect
Firmware dialect to speak (defaults to gdprText)
encryption: Encryption
Encryption instance for payload encryption/decryption
fetch: globalThis.fetch
Swappable fetch, for tests or non-standard HTTP stacks
sequence: number
Sequence number for request signing
sessionId: string
Session ID from authentication
tokenId: string
Security token from authentication

ExecuteResult

Result of executing one or more actions on the router.

actions: ActionResult[]
Array of action results, positionally aligned with the input actions
error: number | null
Error code from router, or null if successful

PublicKeyInfo

RSA public key material and the request sequence base.

exponent: Uint8Array
RSA public exponent, big-endian.
modulus: Uint8Array
RSA modulus, big-endian. Its length fixes the RSA chunk size.
sequence: number
Sequence base that every signature's s parameter is derived from.

RouterInfo

Variables scraped from the router's login page.

authTimes: number
Login attempt counter, sent back as the loginErrorShow cookie.

SessionContext

Session material carried on every request made after login.

authTimes: number
Login attempt counter, sent back as the loginErrorShow cookie.
sessionId: string
JSESSIONID cookie value returned by the login response.
tokenId: string
Token scraped from the authenticated landing page.

Type Aliases

Action = [

ActionType,

string,

Record<string, string> | string[],

string,

string

]

Action tuple representing a single router command.

ActionType = (ACT)[keyof ACT]

Numeric action type value from the ACT constant.

Variables

ACT: { GET: number; SET: number; ADD: number; DEL: number; GL: number; GS: number; OP: number; CGI: number; }

Action type constants for TP-Link router commands.

gdprJson: Dialect

EU/GDPR firmware speaking a JSON payload format over /cgi_gdpr?9.

gdprText: Dialect

EU/GDPR firmware speaking the bespoke text payload format over /cgi_gdpr.

dialect/mod.ts

Firmware dialects for the TP-Link router API.

Examples

Select a dialect for a router that speaks JSON

import { assertEquals } from "@std/assert";
import { gdprJson, gdprText } from "./mod.ts";

assertEquals(gdprText.defaultUsername, "admin");
assertEquals(gdprJson.defaultUsername, "user");

Derive a dialect for a model that differs in one place

import { assertEquals } from "@std/assert";
import { type Dialect, gdprJson } from "./mod.ts";

const vx800v: Dialect = {
  ...gdprJson,
  id: "vx800v",
  publicKeyRequest: (baseUrl) =>
    new Request(new URL("cgi/getParm", baseUrl), { method: "POST" }),
};

assertEquals(
  vx800v.publicKeyRequest("http://192.168.1.1").url,
  "http://192.168.1.1/cgi/getParm",
);
assertEquals(vx800v.defaultUsername, "user");

Interfaces

BusyStatus

isBusy: boolean
Whether the router is busy serving another management session.
isLoggedIn: boolean
Whether a session is already established from another client.

CommandBatch

One HTTP round trip's worth of actions.

indices: readonly number[]
Indices into the caller's actions array, in the order the response returns them.
payload: string
Plaintext payload for this round trip, pre-encryption.

Credentials

Credentials as supplied by the caller, after the dialect's username default has been applied.

password: string
Account password, verbatim.
username: string
Account name, defaulted from Dialect.defaultUsername.

DecodedBatch

Decoded result of one round trip, positionally aligned with CommandBatch.indices.

error: number | null
Router error code, or null when the batch reported no error.
results: readonly (Record<string, string> | Record<string, string>[] | null)[]
One entry per index in the batch; null where the router returned nothing.

Dialect

A firmware family's wire protocol, expressed as pure functions and data.

busyRequest(baseUrl: string): Request
Builds the request that reports whether a session is already established.
commandRequest(
baseUrl: string,
envelope: Envelope,
session: SessionContext
): Request
Builds a command request for one batch's envelope.
decodeCommand(
text: string,
batch: CommandBatch
): DecodedBatch
Decodes a decrypted command response into results aligned with the batch.
defaultUsername: string
Username used when the caller supplies none.
encodeCommands(actions: readonly Action[]): readonly CommandBatch[]
Splits actions into round trips and serializes each. Owns the operation vocabulary, stack defaults, and batching.
encodeLogin(credentials: Credentials): string
Encodes credentials into the plaintext login payload, pre-encryption.
id: string
Stable identifier, carried on the authentication result for diagnostics.
infoRequest(baseUrl: string): Request
Builds the request for the login page, whose inline script carries authTimes and friends.
loginRequest(
baseUrl: string,
envelope: Envelope
): Request
Builds the login request. Owns where the envelope rides — query string, request body, or anywhere else the firmware expects it.
parseBusy(text: string): BusyStatus
Extracts login and busy flags from the busy response.
parseInfo(html: string): RouterInfo
Scrapes router variables out of the login page.
parsePublicKey(text: string): PublicKeyInfo
Extracts RSA parameters from the public key response.
parseSessionId(headers: Headers): string | null
Extracts the session id from the login response headers.
parseTokenId(html: string): string
Extracts the security token from the authenticated page.
publicKeyRequest(baseUrl: string): Request
Builds the request for the RSA public key and sequence base.
tokenRequest(
baseUrl: string,
session: Pick<SessionContext, "sessionId" | "authTimes">
): Request
Builds the request for the authenticated page carrying the security token.

Envelope

Encrypted request envelope: AES ciphertext plus the RSA-encrypted signature.

data: string
Base64 AES-CBC ciphertext of the plaintext payload.
sign: string
Hex RSA-encrypted parameter string: key&iv&h&s for login, h&s for commands.

PublicKeyInfo

RSA public key material and the request sequence base.

exponent: Uint8Array
RSA public exponent, big-endian.
modulus: Uint8Array
RSA modulus, big-endian. Its length fixes the RSA chunk size.
sequence: number
Sequence base that every signature's s parameter is derived from.

RouterInfo

Variables scraped from the router's login page.

authTimes: number
Login attempt counter, sent back as the loginErrorShow cookie.

SessionContext

Session material carried on every request made after login.

authTimes: number
Login attempt counter, sent back as the loginErrorShow cookie.
sessionId: string
JSESSIONID cookie value returned by the login response.
tokenId: string
Token scraped from the authenticated landing page.

Type Aliases

Action = [

ActionType,

string,

Record<string, string> | string[],

string,

string

]

Action tuple representing a single router command.

ActionType = (ACT)[keyof ACT]

Numeric action type value from the ACT constant.

Variables

ACT: { GET: number; SET: number; ADD: number; DEL: number; GL: number; GS: number; OP: number; CGI: number; }

Action type constants for TP-Link router commands.

gdprJson: Dialect

EU/GDPR firmware speaking a JSON payload format over /cgi_gdpr?9.

gdprText: Dialect

EU/GDPR firmware speaking the bespoke text payload format over /cgi_gdpr.