@serve.zone/platformclient is the TypeScript SDK for talking to serve.zone platform services from application code. It wraps the serve.zone TypedSocket API and exposes focused connectors for transactional email, SMS, push notifications, and physical letters.

Use it when your app should trigger serve.zone communication workflows without manually wiring TypedRequest methods or transport setup.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

Installation

pnpm add @serve.zone/platformclient

What It Does

SzPlatformClient handles the shared serve.zone platform connection and gives you these connectors:

Connector	Purpose	TypedRequest method
`emailConnector`	Send transactional email	`sendEmail`
`smsConnector`	Send SMS messages and verification codes	`sendSms`, `sendVerificationCode`
`pushNotificationConnector`	Send push notifications	`sendPushNotification`
`letterConnector`	Send physical letters through the platform	`sendLetter`

Requests use the types from @serve.zone/interfaces, so payloads stay aligned with the serve.zone backend contracts.

Quick Start

import { SzPlatformClient } from '@serve.zone/platformclient';

const platformClient = new SzPlatformClient(process.env.SERVEZONE_PLATFORM_AUTHORIZATION);
await platformClient.init();

await platformClient.emailConnector.sendEmail({
  to: 'user@example.com',
  from: 'hello@serve.zone',
  title: 'Welcome to the platform',
  body: 'Your workspace is ready.',
});

The client connects to the platform endpoint configured through SERVEZONE_PLATFORM_URL or a runtime platform binding.

Configuration

The client needs two values:

Value	How to provide it	Notes
Authorization token	Constructor argument, `init()` argument, `SERVEZONE_PLATFORM_AUTHORIZATION`, `SERVEZONE_PLATFORM_TOKEN`, or binding credential env	Loaded on demand through `@push.rocks/qenv`.
Platform URL	Constructor options, `SERVEZONE_PLATFORM_URL`, or binding endpoint	Loaded on demand through `@push.rocks/qenv`.
Runtime bindings	Constructor options, `SERVEZONE_PLATFORM_BINDING`, or `SERVEZONE_PLATFORM_BINDINGS`	Values are JSON-encoded `IPlatformBinding` objects from `@serve.zone/interfaces`.

const client = new SzPlatformClient();
await client.init('your-platform-authorization-token');

Constructor and init() also accept options:

const client = new SzPlatformClient({
  token: process.env.SERVEZONE_PLATFORM_TOKEN,
  platformUrl: process.env.SERVEZONE_PLATFORM_URL,
});
await client.init();

Debug Mode

Pass test as the authorization string to enable debug mode. In debug mode, the client does not open a TypedSocket connection and connector methods log or return deterministic test values instead of sending real platform requests.

const client = new SzPlatformClient('test');
await client.init();

await client.emailConnector.sendEmail({
  to: 'developer@example.com',
  from: 'hello@serve.zone',
  title: 'Preview only',
  body: 'This message is logged, not sent.',
});

const verificationCode = await client.smsConnector.sendSmsVerifcation({
  toNumber: 491234567890,
  fromName: 'ServeZone',
});
// verificationCode === '123456'

Connector Examples

Email

await client.emailConnector.sendEmail({
  to: 'user@example.com',
  from: 'hello@serve.zone',
  title: 'Invoice ready',
  body: 'Your invoice is available in the dashboard.',
});

SMS

const status = await client.smsConnector.sendSms({
  toNumber: 491234567890,
  fromName: 'ServeZone',
  messageText: 'Your code is 123456.',
});

SMS Verification

const code = await client.smsConnector.sendSmsVerifcation({
  toNumber: 491234567890,
  fromName: 'ServeZone',
});

Push Notifications

const status = await client.pushNotificationConnector.sendPushNotification({
  deviceToken: 'device-token-from-your-app',
  message: 'Deployment complete: your service is live.',
});

Letters

await client.letterConnector.sendLetter({
  description: 'Important account information',
  needsCover: true,
  title: 'Account update',
  coverBody: 'This letter was generated through serve.zone.',
  service: ['Einschreiben'],
});

Exact request fields are defined by @serve.zone/interfaces and may evolve with the platform API.

InfoHtml Helper

The repository also contains an InfoHtml helper in ts_infohtml/ for rendering simple branded informational HTML pages from text or option objects.

import { InfoHtml } from './ts_infohtml/index.js';

const infoPage = await InfoHtml.fromOptions({
  title: 'Service unavailable',
  heading: 'Maintenance in progress',
  text: 'Please try again in a few minutes.',
  redirectTo: 'https://serve.zone',
});

console.log(infoPage.htmlString);

Development

pnpm install
pnpm test
pnpm run build

The package is authored in TypeScript and builds the source folders through tsbuild tsfolders --web --allowimplicitany.

Links

Resource	URL
npm package	https://www.npmjs.com/package/@serve.zone/platformclient
Source	https://gitlab.com/serve.zone/platformclient
Source mirror	https://github.com/serve.zone/platformclient
Typedoc	https://serve.zone.gitlab.io/platformclient/

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 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.

readme.md

@serve.zone/platformclient