@serve.zone/platformclient 1.1.4 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/platformclient",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "private": false,
   "description": "a module that makes it really easy to use the serve.zone platform inside your app",
   "main": "dist_ts/index.js",
@@ -9,29 +9,30 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsbundle": "^2.10.0",
-    "@git.zone/tsrun": "^2.0.2",
-    "@git.zone/tstest": "^3.6.3",
-    "@types/node": "^25.6.0"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsbundle": "^2.11.0",
+    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tstest": "^3.6.6",
+    "@types/node": "^25.9.1"
   },
   "dependencies": {
     "@api.global/typedrequest": "^3.3.0",
-    "@api.global/typedserver": "^8.4.6",
+    "@api.global/typedserver": "^8.5.3",
     "@api.global/typedsocket": "^4.1.2",
-    "@push.rocks/qenv": "^6.1.3",
+    "@push.rocks/qenv": "^6.1.4",
     "@push.rocks/smartlog": "^3.2.2",
-    "@push.rocks/smartntml": "^2.0.8",
-    "@serve.zone/interfaces": "^5.4.5"
+    "@push.rocks/smartntml": "^2.0.9",
+    "@push.rocks/smartsmtp": "^3.1.0",
+    "@serve.zone/interfaces": "^7.27.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/serve.zone/platformclient.git"
+    "url": "git+https://code.foss.global/serve.zone/platformclient.git"
   },
   "bugs": {
-    "url": "https://gitlab.com/serve.zone/platformclient/issues"
+    "url": "https://code.foss.global/serve.zone/platformclient/issues"
   },
-  "homepage": "https://gitlab.com/serve.zone/platformclient#readme",
+  "homepage": "https://code.foss.global/serve.zone/platformclient#readme",
   "browserslist": [
     "last 1 chrome versions"
   ],

package/readme.md

@@ -1,78 +1,85 @@
 # @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` | `getServiceMailStatus()`, `getServiceMailCredentials()`, `sendMail()`, `sendText()`, `sendHtml()`, `normalizeInboundMessage()`, `handleInboundPayload()`, `createInboundHandler()`, `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`.
+
+Service mail credentials can be provided directly as environment variables or through `email` platform binding credentials. The default sender uses `MAIL_FROM`, `SMTP_HOST`, `SMTP_PORT`, `SMTP_TLS_MODE`, `SMTP_USERNAME`, and `SMTP_PASSWORD`. Additional configured sender addresses use scoped variables such as `MAIL_TEST_SERVICE_GATED_ONE_FROM` and `MAIL_TEST_SERVICE_GATED_ONE_SMTP_USERNAME`.
 
 ```typescript
-const client = new SzPlatformClient();
-await client.init('your-platform-authorization-token');
-```
+import { SzPlatformClient } from '@serve.zone/platformclient';
 
-Constructor and `init()` also accept options:
+const client = new SzPlatformClient(process.env.SERVEZONE_PLATFORM_AUTHORIZATION);
+await client.init();
+```
 
 ```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 +87,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,42 +96,70 @@ 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
+Service mail over managed SMTP credentials:
 
 ```typescript
-await client.emailConnector.sendEmail({
+const status = await client.emailConnector.getServiceMailStatus();
+
+if (status.ready) {
+  await client.emailConnector.sendText({
+    to: 'user@example.com',
+    subject: 'Service mail ready',
+    text: 'This message was sent through the managed service mail identity.',
+  });
+}
+```
+
+Specific sender address:
+
+```typescript
+await client.emailConnector.sendHtml({
+  from: 'test-service@gated.one',
   to: 'user@example.com',
-  from: 'hello@serve.zone',
-  title: 'Invoice ready',
-  body: 'Your invoice is available in the dashboard.',
+  subject: 'Platform capability test',
+  html: '<p>The service mail identity is working.</p>',
 });
 ```
 
-### SMS
+Inbound message normalization for webhook or TypedRequest-style delivery:
 
 ```typescript
-const status = await client.smsConnector.sendSms({
-  toNumber: 491234567890,
-  fromName: 'ServeZone',
-  messageText: 'Your code is 123456.',
+const inboundHandler = client.emailConnector.createInboundHandler(async (message) => {
+  console.log(message.from, message.to, message.subject);
+  return { accepted: true };
 });
 ```
 
-### SMS Verification
+Legacy platform-service email request:
 
 ```typescript
-const code = await client.smsConnector.sendSmsVerifcation({
+await client.emailConnector.sendEmail({
+  to: 'user@example.com',
+  from: 'hello@example.com',
+  title: 'Invoice ready',
+  body: 'Your invoice is available in the dashboard.',
+});
+```
+
+SMS:
+
+```typescript
+const status = await client.smsConnector.sendSms({
   toNumber: 491234567890,
   fromName: 'ServeZone',
+  messageText: 'Your code is 123456.',
 });
 ```
 
-### Push Notifications
+Push notification:
 
 ```typescript
 const status = await client.pushNotificationConnector.sendPushNotification({
@@ -133,7 +168,7 @@ const status = await client.pushNotificationConnector.sendPushNotification({
 });
 ```
 
-### Letters
+Letter:
 
 ```typescript
 await client.letterConnector.sendLetter({
@@ -145,25 +180,32 @@ await client.letterConnector.sendLetter({
 });
 ```
 
-Exact request fields are defined by `@serve.zone/interfaces` and may evolve with the platform API.
+Service-mail helper option and result types are exported from `@serve.zone/platformclient`. The legacy platform-service request fields are defined in `@serve.zone/interfaces` under `platform.email`, `platform.sms`, `platform.pushnotification`, and `platform.letter`.
 
-## InfoHtml Helper
+## Platform Bindings
 
-The repository also contains an `InfoHtml` helper in `ts_infohtml/` for rendering simple branded informational HTML pages from text or option objects.
+Platform bindings allow a workload to discover endpoint URLs and credentials from its runtime environment.
 
 ```typescript
-import { InfoHtml } from './ts_infohtml/index.js';
+import { SzPlatformClient } from '@serve.zone/platformclient';
+import { platform } from '@serve.zone/interfaces';
 
-const infoPage = await InfoHtml.fromOptions({
-  title: 'Service unavailable',
-  heading: 'Maintenance in progress',
-  text: 'Please try again in a few minutes.',
-  redirectTo: 'https://serve.zone',
-});
+const binding: platform.IPlatformBinding = JSON.parse(
+  process.env.SERVEZONE_PLATFORM_BINDING!
+);
+
+const client = new SzPlatformClient({ binding });
+await client.init();
 
-console.log(infoPage.htmlString);
+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 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
 
 ```bash
@@ -172,16 +214,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 +230,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.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/platformclient',
-  version: '1.1.4',
+  version: '1.2.0',
   description: 'a module that makes it really easy to use the serve.zone platform inside your app'
 }

package/ts/classes.platformclient.ts

@@ -217,7 +217,7 @@ export class SzPlatformClient {
     return Array.from(bindingMap.values());
   }
 
-  private async getConfiguredEnvVar(envNameArg: string) {
+  public async getConfiguredEnvVar(envNameArg: string) {
     const processValue = this.getProcessEnvVar(envNameArg);
     if (processValue) {
       return processValue;