# @serve.zone/dcrouter-apiclient

> Object-oriented TypeScript client and shared TypedRequest contracts for the dcrouter OpsServer API.

Latest version **32.3.1** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @serve.zone/dcrouter-apiclient
pnpm add @serve.zone/dcrouter-apiclient
yarn add @serve.zone/dcrouter-apiclient
bun add @serve.zone/dcrouter-apiclient
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 32.3.1 |
| Published | 2026-09-24 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Task Venture Capital GmbH |
| Maintainers | lossless |
| Keywords | mail service, SMS, letter delivery, AI services, SMTP server, mail parsing, DKIM, mail router, letterXpress, OpenAI, Anthropic AI, DKIM signing, mail forwarding, SMTP TLS, domain management, email templating, rule management, SMTP STARTTLS, DNS management, RADIUS, AAA, network authentication, VLAN assignment, MAC authentication |

## Links

- npm: https://www.npmjs.com/package/@serve.zone/dcrouter-apiclient
- npm.io page: https://npm.io/package/@serve.zone/dcrouter-apiclient

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 32.3.1 (latest) — 2026-09-24
- 32.3.0 — 2026-09-23

## README

# @serve.zone/dcrouter-apiclient

`@serve.zone/dcrouter-apiclient` is the object-oriented TypeScript client for the dcrouter OpsServer API. It wraps `/typedrequest` calls in managers, builders, and resource classes for routes, certificates, API tokens, remote ingress, email, stats, config, logs, RADIUS, and gateway-client integrations.

It is the client half of dcrouter without the server: installing it does not pull the runtime, the dashboard, the database client or a native password hasher. It ships the shared contracts alongside the client under the `./interfaces` subpath, so a consumer that only reads request and data types never needs `@serve.zone/dcrouter` either.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
pnpm add @serve.zone/dcrouter-apiclient
```

Two entry points:

```typescript
import { DcRouterApiClient } from '@serve.zone/dcrouter-apiclient';
import { data, requests } from '@serve.zone/dcrouter-apiclient/interfaces';
```

The same client and contracts remain available as subpaths of the server package for consumers that already depend on it:

```typescript
import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
import { data, requests } from '@serve.zone/dcrouter/interfaces';
```

### Platform support

**This package installs on Linux x64 and arm64 only.** Several contract members are typed against `@push.rocks/smartmta`, `@push.rocks/smartproxy` and `@push.rocks/smartnetwork`, so those packages are dependencies even though the imports are type-only, and `@push.rocks/smartmta` declares `os: ["linux"]` with `cpu: ["x64", "arm64"]`. Installing anywhere else fails with `ERR_PNPM_UNSUPPORTED_PLATFORM`. `@serve.zone/dcrouter` carries the same constraint today, so this is not a new restriction — but it does mean the client cannot yet be installed on a macOS or Windows developer machine.

The restriction is upstream and no change here lifts it. It goes away once `@push.rocks/smartproxy`, `@push.rocks/smartmta` and `@push.rocks/smartnetwork` move their Rust payloads into per-platform optional packages; today each of the three ships both the amd64 and the arm64 binary in one tarball and declares no macOS or Windows build.

## Quick Start

```typescript
import { DcRouterApiClient } from '@serve.zone/dcrouter-apiclient';

const client = new DcRouterApiClient({
  baseUrl: 'https://dcrouter.example.com',
});

await client.login('admin@example.com', 'strong-password');

const { routes, warnings } = await client.routes.list();
console.log(routes.length, warnings.length);

const route = await client.routes.build()
  .setName('api-gateway')
  .setMatch({ ports: 443, domains: ['api.example.com'] })
  .setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8080 }] })
  .save();

await route.toggle(true);
```

## Authentication

The client supports persisted-admin session login and API-token authentication. Initial admin creation is a bootstrap flow exposed by the Ops dashboard and raw TypedRequest contracts; after a persisted admin exists, use that account with `login()`.

```typescript
const sessionClient = new DcRouterApiClient({
  baseUrl: 'https://dcrouter.example.com',
});
await sessionClient.login('admin@example.com', 'strong-password');

const tokenClient = new DcRouterApiClient({
  baseUrl: 'https://dcrouter.example.com',
  apiToken: 'dcr_token_value',
});
```

`baseUrl` is normalized by removing trailing slashes. Ordinary requests are sent to `${baseUrl}/typedrequest`; log streams use a dedicated TypedSocket connection. `buildRequestPayload()` injects the current identity and optional API token for manager methods.

## Manager Map

| Manager | Purpose |
| --- | --- |
| `client.routes` | List merged routes, build/update/delete ordinary operator routes, and toggle routes. |
| `client.certificates` | Inspect certificate summaries and trigger certificate operations. |
| `client.apiTokens` | Create, list, toggle, roll, and revoke API tokens. |
| `client.remoteIngress` | Manage edge registrations, statuses, ports, tags, and connection tokens. |
| `client.emails` | Inspect received/cached email items and trigger resend flows. |
| `client.gatewayClients` | Manage gateway-client route, DNS, and domain integration calls. |
| `client.stats` | Read health, counters, summaries, and runtime status. |
| `client.config` | Read the current configuration view. |
| `client.logs` | Read recent logs or receive a live log stream. |
| `client.radius` | Manage RADIUS clients, VLAN mappings, and accounting sessions. |

## Log Streams

Log streaming requires a dcrouter server using TypedSocket 8. Each stream owns
one connection, which is released when the stream closes or aborts. Access needs
`logs:read` and is revalidated on the same physical peer during streaming.

```typescript
try {
  const { logStream } = await client.logs.getStream({ follow: false });
  try {
    await logStream.opened;
    const decoder = new TextDecoder();
    for (;;) {
      const chunk = await logStream.receive();
      if (chunk === undefined) break;
      console.log(JSON.parse(decoder.decode(chunk)));
    }
    await logStream.accept();
  } catch (error) {
    await logStream.abort(error);
    throw error;
  }
} finally {
  await client.stop();
}
```

Use `follow: true` for ongoing logs and call `logStream.abort()` when finished,
including when no entries are arriving. Await each receive to apply backpressure.
`client.logs.close()` closes current streams while allowing a later session;
`client.stop()` permanently closes log streaming on that client instance.
Logout closes current streams and permits a later login.

## Route Builder

```typescript
const route = await client.routes.build()
  .setName('internal-app')
  .setMatch({
    ports: 443,
    domains: ['internal.example.com'],
  })
  .setAction({
    type: 'forward',
    targets: [{ host: '127.0.0.1', port: 3000 }],
  })
  .setEnabled(true)
  .save();

await route.update({
  action: {
    type: 'forward',
    targets: [{ host: '127.0.0.1', port: 3001 }],
  },
});
```

System routes from `config`, `email`, and `dns` origins are designed to be toggled, not edited. Generic create/update/delete behavior is for ordinary operator-owned routes with origin `api`. API-origin routes carrying managed ownership metadata, including gateway-client routes and HTTP-01 Special Forwards, must be changed through their owning specialized TypedRequest workflow; `client.routes` does not bypass that protection.

## API Tokens and Remote Ingress

```typescript
const token = await client.apiTokens.build()
  .setName('automation')
  .setScopes(['routes:read', 'routes:write'])
  .setExpiresInDays(30)
  .save();

const edge = await client.remoteIngress.build()
  .setName('edge-eu-1')
  .setListenPorts([80, 443])
  .setAutoDerivePorts(true)
  .setEgress({
    enabled: true,
    allowedPorts: [25],
    allowedHostPatterns: ['*.example.com'],
    maxConcurrentStreams: 100,
  })
  .setTags(['production', 'eu'])
  .save();

const connectionToken = await edge.getConnectionToken();
console.log(token.tokenValue, connectionToken);
```

RemoteIngress resources expose `performance` and `egress` fields. `create()` and `update()` accept the same fields as the builder. Egress is default-disabled; dcrouter currently accepts outbound SMTP egress on port `25` only.

## What This Package Is Not

- It does not start dcrouter.
- It does not serve or bundle the Ops dashboard.
- It does not replace the raw dcrouter-local TypedRequest contracts under `@serve.zone/dcrouter-apiclient/interfaces` when you want to talk to `/typedrequest` yourself.

Use `@serve.zone/dcrouter` for the server runtime. The canonical machine-facing gateway client route, DNS, and domain contracts used by `client.gatewayClients` come from `@serve.zone/interfaces`.

## Development

This folder is published from the dcrouter monorepo through its `tspublish.json`, which also owns `ts_interfaces` and exposes it as the `./interfaces` subpath. Both folders keep the build order they always had (`ts_interfaces` first, then `ts_apiclient`). See `../ts_interfaces/readme.md` for the contract surface. `gitzone release` publishes this package in the same release as `@serve.zone/dcrouter` and the Docker images, at the same version and before the runtime package.

Useful source entry points:

- `index.ts` exports the public client surface.
- `classes.dcrouterapiclient.ts` owns authentication and request dispatch.
- `classes.route.ts` owns route resources and builders.
- `classes.remoteingress.ts`, `classes.apitoken.ts`, `classes.radius.ts`, and the other manager files wrap focused API domains.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH  
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

---
_Source: https://npm.io/package/@serve.zone/dcrouter-apiclient · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._