serve.zone/platformclient
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: refresh readme and legal info

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-07 20:22:12 +00:00
parent ec93151d31
commit f38938ef3d
2 changed files with 84 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+74 -77
View File
@@ -1,78 +1,83 @@
# @serve.zone/platformclient
`@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.
`@serve.zone/platformclient` is the application SDK for serve.zone platform services. It opens a TypedSocket connection to a platform endpoint and gives application code focused connectors for transactional email, SMS, push notifications, and physical letters without hand-writing TypedRequest setup.
## 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.
## Installation
## Install
```bash
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
```typescript
import { SzPlatformClient } from '@serve.zone/platformclient';
const platformClient = new SzPlatformClient(process.env.SERVEZONE_PLATFORM_AUTHORIZATION);
const platformClient = new SzPlatformClient({
token: process.env.SERVEZONE_PLATFORM_TOKEN,
platformUrl: process.env.SERVEZONE_PLATFORM_URL,
});
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.',
from: 'hello@example.com',
title: 'Workspace ready',
body: 'Your serve.zone workspace is ready.',
});
```
The client connects to the platform endpoint configured through `SERVEZONE_PLATFORM_URL` or a runtime platform binding.
## Connectors
`SzPlatformClient` owns the shared connection and exposes connector instances:
| Connector | Main methods | Platform capability |
| --- | --- | --- |
| `emailConnector` | `sendEmail()` | `email` |
| `smsConnector` | `sendSms()`, `sendSmsVerifcation()` | `sms` |
| `pushNotificationConnector` | `sendPushNotification()` | `pushnotification` |
| `letterConnector` | `sendLetter()` | `letter` |
The request and response payloads come from `@serve.zone/interfaces`, so TypeScript stays aligned with the serve.zone platform contracts.
## Configuration
The client needs two values:
The client needs an authorization string and a platform endpoint. You can provide both directly, through environment variables, or through platform bindings.
| 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`. |
| Value | Sources |
| --- | --- |
| Authorization | Constructor string, `authorizationString`, `authorization`, `token`, `init()` argument, `SERVEZONE_PLATFORM_AUTHORIZATION`, `SERVEZONE_PLATFORM_TOKEN`, or binding credentials. |
| Platform URL | `url`, `platformUrl`, `SERVEZONE_PLATFORM_URL`, or the first active binding endpoint using `typedrequest` or `http`. |
| Platform bindings | Constructor `binding` or `bindings`, `SERVEZONE_PLATFORM_BINDING`, or `SERVEZONE_PLATFORM_BINDINGS`. |
Binding environment variables must contain JSON encoded `IPlatformBinding` objects from `@serve.zone/interfaces`.
```typescript
const client = new SzPlatformClient();
await client.init('your-platform-authorization-token');
import { SzPlatformClient } from '@serve.zone/platformclient';
const client = new SzPlatformClient(process.env.SERVEZONE_PLATFORM_AUTHORIZATION);
await client.init();
```
Constructor and `init()` also accept options:
```typescript
import { SzPlatformClient } from '@serve.zone/platformclient';
const client = new SzPlatformClient({
token: process.env.SERVEZONE_PLATFORM_TOKEN,
platformUrl: process.env.SERVEZONE_PLATFORM_URL,
authorization: process.env.SERVEZONE_PLATFORM_AUTHORIZATION,
url: 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.
Pass `test` as the authorization string to activate debug mode. In debug mode, the client does not open a TypedSocket connection. Connector methods log or return deterministic test values instead of sending real platform requests.
```typescript
const client = new SzPlatformClient('test');
@@ -80,7 +85,7 @@ await client.init();
await client.emailConnector.sendEmail({
to: 'developer@example.com',
from: 'hello@serve.zone',
from: 'hello@example.com',
title: 'Preview only',
body: 'This message is logged, not sent.',
});
@@ -89,23 +94,26 @@ const verificationCode = await client.smsConnector.sendSmsVerifcation({
toNumber: 491234567890,
fromName: 'ServeZone',
});
// verificationCode === '123456'
console.log(verificationCode); // 123456
```
The current SMS verification method is spelled `sendSmsVerifcation()` in code. Use that exact method name until the public API changes.
## Connector Examples
### Email
Email:
```typescript
await client.emailConnector.sendEmail({
to: 'user@example.com',
from: 'hello@serve.zone',
from: 'hello@example.com',
title: 'Invoice ready',
body: 'Your invoice is available in the dashboard.',
});
```
### SMS
SMS:
```typescript
const status = await client.smsConnector.sendSms({
@@ -115,16 +123,7 @@ const status = await client.smsConnector.sendSms({
});
```
### SMS Verification
```typescript
const code = await client.smsConnector.sendSmsVerifcation({
toNumber: 491234567890,
fromName: 'ServeZone',
});
```
### Push Notifications
Push notification:
```typescript
const status = await client.pushNotificationConnector.sendPushNotification({
@@ -133,7 +132,7 @@ const status = await client.pushNotificationConnector.sendPushNotification({
});
```
### Letters
Letter:
```typescript
await client.letterConnector.sendLetter({
@@ -145,24 +144,31 @@ await client.letterConnector.sendLetter({
});
```
Exact request fields are defined by `@serve.zone/interfaces` and may evolve with the platform API.
Exact fields are defined in `@serve.zone/interfaces` under `platform.email`, `platform.sms`, `platform.pushnotification`, and `platform.letter`.
## Platform Bindings
Platform bindings allow a workload to discover endpoint URLs and credentials from its runtime environment.
```typescript
import { SzPlatformClient } from '@serve.zone/platformclient';
import { platform } from '@serve.zone/interfaces';
const binding: platform.IPlatformBinding = JSON.parse(
process.env.SERVEZONE_PLATFORM_BINDING!
);
const client = new SzPlatformClient({ binding });
await client.init();
const emailBinding = client.getPlatformBinding('email');
```
Bindings with `desiredState: 'disabled'` or `status: 'failed'` are ignored when the client auto-selects an endpoint.
## InfoHtml Helper
The repository also contains an `InfoHtml` helper in `ts_infohtml/` for rendering simple branded informational HTML pages from text or option objects.
```typescript
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);
```
The repository also contains a small `ts_infohtml` source folder for rendering simple informational HTML pages from text or options. It is not exported from the package root, so treat it as a source-level helper rather than the main SDK API.
## Development
@@ -172,16 +178,7 @@ 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/> |
The package is authored as ESM TypeScript and builds source folders with `tsbuild tsfolders --web --allowimplicitany`.
## License and Legal Information
@@ -197,7 +194,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
### Company Information
Task Venture Capital GmbH
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.
ts_infohtml/template.ts
+10 -7
View File
@@ -36,6 +36,11 @@ export const simpleInfo = async (
width: 150px;
padding-top: 70px;
margin: 0px auto 30px auto;
color: #ffffff;
text-align: center;
font-size: 24px;
font-weight: 700;
letter-spacing: 0.08em;
}
.content {
@@ -115,9 +120,7 @@ export const simpleInfo = async (
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div class="logo">
<img src="https://assetbroker.lossless.one/brandfiles/lossless/svg-minimal-bright.svg" />
</div>
<div class="logo">serve.zone</div>
<div class="content">
${(() => {
const returnArray: plugins.smartntml.deesElement.TemplateResult[] = [];
@@ -136,7 +139,7 @@ export const simpleInfo = async (
html`<div class="addontext">
We recorded this event. Should you continue to see this page against your
expectations, feel free to mail us at
<a href="mailto:hello@lossless.com">hello@lossless.com</a>
<a href="mailto:hello@task.vc">hello@task.vc</a>
</div>`
);
}
@@ -151,9 +154,9 @@ export const simpleInfo = async (
})()}
</div>
<div class="legal">
<a href="https://lossless.com">Lossless GmbH</a> / &copy 2014-${new Date().getFullYear()}
/ <a href="https://lossless.gmbh">Legal Info</a> /
<a href="https://lossless.gmbh">Privacy Policy</a>
<a href="https://task.vc">Task Venture Capital GmbH</a> / &copy 2014-${new Date().getFullYear()}
/ <a href="https://task.vc">Legal Info</a> /
<a href="https://task.vc">Privacy Policy</a>
</div>
</body>
</html>