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
`@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. `@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.
Use it when your app should trigger serve.zone communication workflows without manually wiring TypedRequest methods or transport setup.
## Issue Reporting and Security ## 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. 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 ```bash
pnpm add @serve.zone/platformclient 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 ## Quick Start
```typescript ```typescript
import { SzPlatformClient } from '@serve.zone/platformclient'; 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.init();
await platformClient.emailConnector.sendEmail({ await platformClient.emailConnector.sendEmail({
to: 'user@example.com', to: 'user@example.com',
from: 'hello@serve.zone', from: 'hello@example.com',
title: 'Welcome to the platform', title: 'Workspace ready',
body: 'Your workspace is 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 ## 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 | | Value | Sources |
| --- | --- | --- | | --- | --- |
| Authorization token | Constructor argument, `init()` argument, `SERVEZONE_PLATFORM_AUTHORIZATION`, `SERVEZONE_PLATFORM_TOKEN`, or binding credential env | Loaded on demand through `@push.rocks/qenv`. | | Authorization | Constructor string, `authorizationString`, `authorization`, `token`, `init()` argument, `SERVEZONE_PLATFORM_AUTHORIZATION`, `SERVEZONE_PLATFORM_TOKEN`, or binding credentials. |
| Platform URL | Constructor options, `SERVEZONE_PLATFORM_URL`, or binding endpoint | Loaded on demand through `@push.rocks/qenv`. | | Platform URL | `url`, `platformUrl`, `SERVEZONE_PLATFORM_URL`, or the first active binding endpoint using `typedrequest` or `http`. |
| Runtime bindings | Constructor options, `SERVEZONE_PLATFORM_BINDING`, or `SERVEZONE_PLATFORM_BINDINGS` | Values are JSON-encoded `IPlatformBinding` objects from `@serve.zone/interfaces`. | | 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 ```typescript
const client = new SzPlatformClient(); import { SzPlatformClient } from '@serve.zone/platformclient';
await client.init('your-platform-authorization-token');
const client = new SzPlatformClient(process.env.SERVEZONE_PLATFORM_AUTHORIZATION);
await client.init();
``` ```
Constructor and `init()` also accept options:
```typescript ```typescript
import { SzPlatformClient } from '@serve.zone/platformclient';
const client = new SzPlatformClient({ const client = new SzPlatformClient({
token: process.env.SERVEZONE_PLATFORM_TOKEN, authorization: process.env.SERVEZONE_PLATFORM_AUTHORIZATION,
platformUrl: process.env.SERVEZONE_PLATFORM_URL, url: process.env.SERVEZONE_PLATFORM_URL,
}); });
await client.init(); await client.init();
``` ```
## Debug Mode ## 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 ```typescript
const client = new SzPlatformClient('test'); const client = new SzPlatformClient('test');
@@ -80,7 +85,7 @@ await client.init();
await client.emailConnector.sendEmail({ await client.emailConnector.sendEmail({
to: 'developer@example.com', to: 'developer@example.com',
from: 'hello@serve.zone', from: 'hello@example.com',
title: 'Preview only', title: 'Preview only',
body: 'This message is logged, not sent.', body: 'This message is logged, not sent.',
}); });
@@ -89,23 +94,26 @@ const verificationCode = await client.smsConnector.sendSmsVerifcation({
toNumber: 491234567890, toNumber: 491234567890,
fromName: 'ServeZone', 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 ## Connector Examples
### Email Email:
```typescript ```typescript
await client.emailConnector.sendEmail({ await client.emailConnector.sendEmail({
to: 'user@example.com', to: 'user@example.com',
from: 'hello@serve.zone', from: 'hello@example.com',
title: 'Invoice ready', title: 'Invoice ready',
body: 'Your invoice is available in the dashboard.', body: 'Your invoice is available in the dashboard.',
}); });
``` ```
### SMS SMS:
```typescript ```typescript
const status = await client.smsConnector.sendSms({ const status = await client.smsConnector.sendSms({
@@ -115,16 +123,7 @@ const status = await client.smsConnector.sendSms({
}); });
``` ```
### SMS Verification Push notification:
```typescript
const code = await client.smsConnector.sendSmsVerifcation({
toNumber: 491234567890,
fromName: 'ServeZone',
});
```
### Push Notifications
```typescript ```typescript
const status = await client.pushNotificationConnector.sendPushNotification({ const status = await client.pushNotificationConnector.sendPushNotification({
@@ -133,7 +132,7 @@ const status = await client.pushNotificationConnector.sendPushNotification({
}); });
``` ```
### Letters Letter:
```typescript ```typescript
await client.letterConnector.sendLetter({ 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 ## InfoHtml Helper
The repository also contains an `InfoHtml` helper in `ts_infohtml/` for rendering simple branded informational HTML pages from text or option objects. 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.
```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);
```
## Development ## Development
@@ -172,16 +178,7 @@ pnpm test
pnpm run build pnpm run build
``` ```
The package is authored in TypeScript and builds the source folders through `tsbuild tsfolders --web --allowimplicitany`. The package is authored as ESM TypeScript and builds source folders with `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 ## License and Legal Information
@@ -197,7 +194,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
### Company Information ### Company Information
Task Venture Capital GmbH Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany 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. 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; width: 150px;
padding-top: 70px; padding-top: 70px;
margin: 0px auto 30px auto; margin: 0px auto 30px auto;
color: #ffffff;
text-align: center;
font-size: 24px;
font-weight: 700;
letter-spacing: 0.08em;
} }
.content { .content {
@@ -115,9 +120,7 @@ export const simpleInfo = async (
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head> </head>
<body> <body>
<div class="logo"> <div class="logo">serve.zone</div>
<img src="https://assetbroker.lossless.one/brandfiles/lossless/svg-minimal-bright.svg" />
</div>
<div class="content"> <div class="content">
${(() => { ${(() => {
const returnArray: plugins.smartntml.deesElement.TemplateResult[] = []; const returnArray: plugins.smartntml.deesElement.TemplateResult[] = [];
@@ -136,7 +139,7 @@ export const simpleInfo = async (
html`<div class="addontext"> html`<div class="addontext">
We recorded this event. Should you continue to see this page against your We recorded this event. Should you continue to see this page against your
expectations, feel free to mail us at 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>` </div>`
); );
} }
@@ -151,9 +154,9 @@ export const simpleInfo = async (
})()} })()}
</div> </div>
<div class="legal"> <div class="legal">
<a href="https://lossless.com">Lossless GmbH</a> / &copy 2014-${new Date().getFullYear()} <a href="https://task.vc">Task Venture Capital GmbH</a> / &copy 2014-${new Date().getFullYear()}
/ <a href="https://lossless.gmbh">Legal Info</a> / / <a href="https://task.vc">Legal Info</a> /
<a href="https://lossless.gmbh">Privacy Policy</a> <a href="https://task.vc">Privacy Policy</a>
</div> </div>
</body> </body>
</html> </html>