@serve.zone/interfaces 5.4.3 → 5.4.5

package/readme.md

@@ -2,7 +2,20 @@
 
 Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.
 
-This package contains the public contracts consumed by Cloudly, Spark, Coreflow, Coretraffic, Platformclient, and external integrations. It is intentionally dependency-light and should not contain runtime implementation code.
+`@serve.zone/interfaces` is the contract package used by Cloudly, Spark, Coreflow, Coretraffic, Platformclient, CLI clients, and external integrators. It contains only public data shapes and typed RPC request definitions, so services can evolve independently while speaking the same language.
+
+## 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.
+
+## What This Package Provides
+
+- `data` contains persistent platform shapes such as clusters, cluster nodes, deployments, services, images, DNS records, domains, secrets, users, identities, settings, status, traffic, server metadata, bare-metal inventory, and task executions.
+- `requests` contains `@api.global/typedrequest-interfaces` contracts for Cloudly and platform RPC methods. Each request defines its method name, request payload, and response payload.
+- `platform` contains current platform-service contracts for email, SMS, push notifications, letters, AI, backups, databases, logging, object storage, and SIP.
+- `platformservice` contains legacy compatibility contracts used by older platform-service clients.
+
+The package intentionally has no service implementation logic. It is a stable shared vocabulary for the rest of serve.zone.
 
 ## Install
 
@@ -10,12 +23,151 @@ This package contains the public contracts consumed by Cloudly, Spark, Coreflow,
 pnpm add @serve.zone/interfaces
 ```
 
-## Usage
+## Public API
+
+```typescript
+import { data, platform, platformservice, requests } from '@serve.zone/interfaces';
+```
+
+The root export exposes four namespaces:
+
+```typescript
+export {
+  data,
+  platform,
+  platformservice,
+  requests,
+};
+```
+
+## Data Interfaces
+
+Use `data` when you need durable serve.zone object shapes.
 
 ```typescript
-import { data, requests, platformservice } from '@serve.zone/interfaces';
+import { data } from '@serve.zone/interfaces';
+
+const service: data.IService = {
+  id: 'service-api',
+  data: {
+    name: 'api',
+    description: 'Public API service',
+    imageId: 'image-api',
+    imageVersion: '1.0.0',
+    environment: {
+      NODE_ENV: 'production',
+    },
+    secretBundleId: 'secretbundle-api',
+    serviceCategory: 'workload',
+    deploymentStrategy: 'limited-replicas',
+    scaleFactor: 2,
+    balancingStrategy: 'round-robin',
+    ports: {
+      web: 3000,
+    },
+    domains: [
+      {
+        name: 'api',
+        protocol: 'https',
+      },
+    ],
+    deploymentIds: [],
+  },
+};
 ```
 
+Common data contracts include:
+
+- `ICluster` and `IClusterNode` for cluster membership and provisioning metadata.
+- `IService`, `IDeployment`, and `IImage` for workload configuration and deployment state.
+- `IDnsEntry`, `IDomain`, and traffic interfaces for routing and domain management.
+- `ISecretBundle` and `ISecretGroup` for secret ownership and grouping.
+- `IUser`, `IIdentity`, and token-related interfaces for authentication context.
+- `ICloudlyConfig`, settings, status, server, bare-metal, and task execution interfaces for control-plane state.
+
+## TypedRequest Contracts
+
+Use `requests` when registering handlers or creating typed clients with `@api.global/typedrequest` or `@api.global/typedsocket`.
+
+```typescript
+import { requests } from '@serve.zone/interfaces';
+
+type GetClustersRequest = requests.cluster.IReq_Any_Cloudly_GetClusters;
+
+const methodName: GetClustersRequest['method'] = 'getClusters';
+```
+
+Each request interface follows the same structure:
+
+```typescript
+interface IExampleRequest {
+  method: 'methodName';
+  request: Record<string, unknown>;
+  response: Record<string, unknown>;
+}
+```
+
+Request groups are exported by domain:
+
+- `requests.admin`
+- `requests.baremetal`
+- `requests.certificate`
+- `requests.cluster`
+- `requests.config`
+- `requests.deployment`
+- `requests.dns`
+- `requests.domain`
+- `requests.externalRegistry`
+- `requests.identity`
+- `requests.image`
+- `requests.inform`
+- `requests.log`
+- `requests.network`
+- `requests.node`
+- `requests.routing`
+- `requests.secretbundle`
+- `requests.secretgroup`
+- `requests.server`
+- `requests.service`
+- `requests.settings`
+- `requests.status`
+- `requests.task`
+- `requests.version`
+
+## Platform Contracts
+
+Use `platform` for current product-facing platform APIs.
+
+```typescript
+import { platform } from '@serve.zone/interfaces';
+
+type SendEmailRequest = platform.email.IReq_SendEmail;
+
+const sendEmailMethod: SendEmailRequest['method'] = 'sendEmail';
+```
+
+Available platform modules:
+
+- `platform.email` for email sending, recipient registration, status checks, and email stats.
+- `platform.sms` for SMS delivery contracts.
+- `platform.pushnotification` for push-notification contracts.
+- `platform.letter` for physical letter workflows.
+- `platform.ai` for AI bridge contracts.
+- `platform.backup`, `platform.database`, `platform.logging`, `platform.objectstorage`, and `platform.sip` for infrastructure-facing platform features.
+- `platform.types` for shared platform service metadata.
+
+## Legacy Platformservice Contracts
+
+`platformservice` is retained for older integrations that still consume the previous namespace layout.
+
+```typescript
+import { platformservice } from '@serve.zone/interfaces';
+
+type LegacySendEmailRequest = platformservice.mta.IRequest_SendEmail;
+```
+
+New code should prefer the `platform` namespace unless it must remain compatible with an existing platformservice consumer.
+
 ## Development
 
 ```bash
@@ -24,6 +176,41 @@ pnpm run build
 pnpm test
 ```
 
-## Ownership
+This package is built with `tsbuild` and tested with `@git.zone/tstest`.
+
+## Ownership Rules
+
+Only ecosystem-wide public contracts belong in this package. Cloudly-internal implementation details, service-private DTOs, and temporary migration helpers should stay in the consuming project until they become real shared contracts.
+
+Good candidates for this package:
+
+- Types persisted or exchanged across multiple serve.zone services.
+- TypedRequest contracts used by more than one project.
+- External SDK-facing interfaces that must remain stable.
+
+Poor candidates for this package:
+
+- Private implementation details of a single service.
+- Convenience wrappers with runtime behavior.
+- Backward-compatibility aliases without an active consumer.
+
+## 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.
 
-Only ecosystem-wide public contracts belong here. Cloudly-internal implementation types should stay in Cloudly.
+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.

package/ts/index.ts

@@ -1,9 +1,11 @@
 import * as data from './data/index.js';
+import * as platform from './platform/index.js';
 import * as platformservice from './platformservice/index.js';
 import * as requests from './requests/index.js';
 
 export {
   data,
+  platform,
   platformservice,
   requests
 }

package/ts/platform/ai.ts

@@ -0,0 +1,23 @@
+import * as plugins from '../plugins.js';
+
+export interface IChat {
+  systemMessage: string;
+  messages: {
+    role: 'assistant' | 'user';
+    content: string;
+  }[];
+}
+
+export interface IReq_Chat extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Chat
+> {
+  method: 'chat';
+  request: {
+    chat: IChat;
+  };
+  response: {
+    chat: IChat;
+    latestMessage: string;
+  };
+}

package/ts/platform/backup.ts

@@ -0,0 +1,10 @@
+export type TPlatformBackupTarget = 'volume' | 'database' | 'bucket';
+
+export interface IPlatformBackupBindingConfig {
+  targets: Array<{
+    type: TPlatformBackupTarget;
+    name: string;
+  }>;
+  schedule: string;
+  retentionDays?: number;
+}

package/ts/platform/database.ts

@@ -0,0 +1,8 @@
+export type TPlatformDatabaseEngine = 'postgres' | 'mongodb' | 'mysql' | 'redis';
+
+export interface IPlatformDatabaseBindingConfig {
+  engine: TPlatformDatabaseEngine;
+  databaseName?: string;
+  version?: string;
+  extensions?: string[];
+}

package/ts/platform/email.ts

@@ -0,0 +1,73 @@
+import * as plugins from '../plugins.js';
+
+export type TTemplates = 'default' | 'linkaction' | 'notification';
+
+export interface IReq_SendEmail extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SendEmail
+> {
+  method: 'sendEmail';
+  request: {
+    title: string;
+    from: string;
+    to: string;
+    body: string;
+    attachments?: Array<{
+      name: string;
+      binaryAttachmentString: string;
+    }>;
+  };
+  response: {
+    responseId: string;
+  };
+}
+
+export interface IReq_RegisterRecipient extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RegisterRecipient
+> {
+  method: 'registerRecipient';
+  request: {
+    emailAddress: string;
+  };
+  response: {
+    status: 'ok' | 'not ok';
+  };
+}
+
+export interface IReq_CheckEmailStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CheckEmailStatus
+> {
+  method: 'checkEmailStatus';
+  request: {
+    emailId: string;
+  };
+  response: {
+    status: string;
+    details?: { message: string };
+  };
+}
+
+export interface IReq_GetEmailStats extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetEmailStats
+> {
+  method: 'getEmailStats';
+  request: {
+    jwt: string;
+  };
+  response: {
+    totalEmailsSent: number;
+    totalEmailsDelivered: number;
+    totalEmailsBounced: number;
+    averageDeliveryTimeMs: number;
+    lastUpdated: string;
+  };
+}
+
+export type IReq_GetEMailStats = IReq_GetEmailStats;
+export type IRequest_SendEmail = IReq_SendEmail;
+export type IRequest_RegisterRecipient = IReq_RegisterRecipient;
+export type IRequest_CheckEmailStatus = IReq_CheckEmailStatus;
+export type IRequest_GetEMailStats = IReq_GetEmailStats;

package/ts/platform/index.ts

@@ -0,0 +1,27 @@
+import * as ai from './ai.js';
+import * as backup from './backup.js';
+import * as database from './database.js';
+import * as email from './email.js';
+import * as letter from './letter.js';
+import * as logging from './logging.js';
+import * as objectstorage from './objectstorage.js';
+import * as pushnotification from './pushnotification.js';
+import * as sip from './sip.js';
+import * as sms from './sms.js';
+import * as types from './types.js';
+
+export {
+  ai,
+  backup,
+  database,
+  email,
+  letter,
+  logging,
+  objectstorage,
+  pushnotification,
+  sip,
+  sms,
+  types,
+};
+
+export * from './types.js';

package/ts/platform/letter.ts

@@ -0,0 +1,26 @@
+import * as plugins from '../plugins.js';
+
+export interface IReq_SendLetter extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SendLetter
+> {
+  method: 'sendLetter';
+  request: {
+    description: string;
+    needsCover: boolean;
+    title?: string;
+    from?: plugins.tsclass.business.IAddress;
+    to?: plugins.tsclass.business.IAddress;
+    coverBody?: string;
+    service: 'Einschreiben'[];
+    pdfAttachments?: Array<{
+      name: string;
+      binaryAttachmentString: string;
+    }>;
+  };
+  response: {
+    processId: string;
+  };
+}
+
+export type IRequest_SendLetter = IReq_SendLetter;

package/ts/platform/logging.ts

@@ -0,0 +1,5 @@
+export interface IPlatformLoggingBindingConfig {
+  streams?: string[];
+  retentionDays?: number;
+  exposeQueryEndpoint?: boolean;
+}

package/ts/platform/objectstorage.ts

@@ -0,0 +1,6 @@
+export interface IPlatformObjectStorageBindingConfig {
+  bucketName?: string;
+  region?: string;
+  publicRead?: boolean;
+  versioning?: boolean;
+}

package/ts/platform/pushnotification.ts

@@ -0,0 +1,18 @@
+import * as plugins from '../plugins.js';
+
+export interface IReq_SendPushNotification extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SendPushNotification
+> {
+  method: 'sendPushNotification';
+  request: {
+    deviceToken: string;
+    message: string;
+  };
+  response: {
+    ok: boolean;
+    status: string;
+  };
+}
+
+export type IRequest_SendPushNotification = IReq_SendPushNotification;

package/ts/platform/sip.ts

@@ -0,0 +1,6 @@
+export interface IPlatformSipBindingConfig {
+  trunkId?: string;
+  extension?: string;
+  inboundNumbers?: string[];
+  outboundCallerId?: string;
+}

package/ts/platform/sms.ts

@@ -0,0 +1,34 @@
+import * as plugins from '../plugins.js';
+
+export interface IReq_SendSms extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SendSms
+> {
+  method: 'sendSms';
+  request: {
+    toNumber: number;
+    fromName: string;
+    messageText: string;
+  };
+  response: {
+    status: 'ok' | 'not ok';
+  };
+}
+
+export interface IReq_SendVerificationCode extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SendVerificationCode
+> {
+  method: 'sendVerificationCode';
+  request: {
+    toNumber: number;
+    fromName: string;
+  };
+  response: {
+    status: 'ok' | 'not ok';
+    verificationCode: string;
+  };
+}
+
+export type IRequest_SendSms = IReq_SendSms;
+export type IRequest_SendVerificationCode = IReq_SendVerificationCode;

package/ts/platform/types.ts

@@ -0,0 +1,82 @@
+export type TPlatformCapability =
+  | 'email'
+  | 'sms'
+  | 'pushnotification'
+  | 'letter'
+  | 'ai'
+  | 'database'
+  | 'objectstorage'
+  | 'logging'
+  | 'backup'
+  | 'sip';
+
+export type TPlatformAccessMode = 'rpc' | 'binding' | 'sidecar' | 'internal';
+export type TPlatformBindingStatus = 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'disabled';
+export type TPlatformDesiredState = 'enabled' | 'disabled';
+export type TPlatformEndpointProtocol =
+  | 'typedrequest'
+  | 'http'
+  | 'tcp'
+  | 'udp'
+  | 'smtp'
+  | 's3'
+  | 'postgres'
+  | 'mongodb'
+  | 'sip';
+
+export type TPlatformConfigValue =
+  | string
+  | number
+  | boolean
+  | null
+  | TPlatformConfigValue[]
+  | { [key: string]: TPlatformConfigValue };
+
+export interface IPlatformCapability {
+  id: TPlatformCapability;
+  title: string;
+  description?: string;
+  accessMode: TPlatformAccessMode;
+  defaultProviderType?: string;
+}
+
+export interface IPlatformProviderConfig {
+  id: string;
+  capability: TPlatformCapability;
+  providerType: string;
+  name: string;
+  enabled: boolean;
+  config?: { [key: string]: TPlatformConfigValue };
+  secretBundleId?: string;
+}
+
+export interface IPlatformCredentialRef {
+  secretBundleId?: string;
+  secretGroupIds?: string[];
+  dockerSecretName?: string;
+  env?: { [key: string]: string };
+}
+
+export interface IPlatformServiceEndpoint {
+  name: string;
+  capability: TPlatformCapability;
+  protocol: TPlatformEndpointProtocol;
+  internalUrl?: string;
+  externalUrl?: string;
+  networkAlias?: string;
+  port?: number;
+}
+
+export interface IPlatformBinding {
+  id: string;
+  serviceId: string;
+  capability: TPlatformCapability;
+  desiredState: TPlatformDesiredState;
+  status: TPlatformBindingStatus;
+  providerConfigId?: string;
+  config?: { [key: string]: TPlatformConfigValue };
+  endpoints?: IPlatformServiceEndpoint[];
+  credentials?: IPlatformCredentialRef[];
+  createdAt?: number;
+  updatedAt?: number;
+}

package/ts/platformservice/aibridge.ts

@@ -20,4 +20,6 @@ export interface IReq_Chat extends plugins.typedrequestInterfaces.implementsTR<
     chat: IChat;
     latestMessage: string;
   }
-}
+}
+
+export type IRequest_Chat = IReq_Chat;

package/ts/platformservice/letter.ts

@@ -31,4 +31,6 @@ export interface IRequest_SendLetter extends plugins.typedrequestInterfaces.impl
      */
     processId: string;
   };
-}
+}
+
+export type IReq_SendLetter = IRequest_SendLetter;

package/ts/platformservice/mta.ts

@@ -68,3 +68,8 @@ export interface IReq_GetEMailStats extends plugins.typedrequestInterfaces.imple
     lastUpdated: string;
   };
 }
+
+export type IRequest_SendEmail = IReq_SendEmail;
+export type IRequest_RegisterRecipient = IReq_RegisterRecipient;
+export type IRequest_CheckEmailStatus = IReq_CheckEmailStatus;
+export type IRequest_GetEMailStats = IReq_GetEMailStats;

package/ts/platformservice/pushnotification.ts

@@ -13,4 +13,6 @@ export interface IRequest_SendPushNotification extends plugins.typedrequestInter
     ok: boolean;
     status: string;
   }
-}
+}
+
+export type IReq_SendPushNotification = IRequest_SendPushNotification;

package/ts/platformservice/sms.ts

@@ -31,3 +31,6 @@ export interface IRequest_SendSms
       verificationCode: string;
     }
   }
+
+export type IReq_SendSms = IRequest_SendSms;
+export type IReq_SendVerificationCode = IRequest_SendVerificationCode;

package/ts/requests/config.ts

@@ -3,6 +3,7 @@ import * as clusterInterfaces from '../data/cluster.js';
 import * as serverInterfaces from '../data/server.js';
 import * as userInterfaces from '../data/user.js';
 import type { IService } from '../data/service.js';
+import type { IPlatformBinding, IPlatformProviderConfig } from '../platform/types.js';
 
 export interface IRequest_Any_Cloudly_GetServerConfig
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -31,6 +32,8 @@ extends plugins.typedrequestInterfaces.implementsTR<
   response: {
     configData: clusterInterfaces.ICluster;
     services: IService[];
+    platformProviderConfigs?: IPlatformProviderConfig[];
+    platformBindings?: IPlatformBinding[];
   };
 }
 
@@ -43,6 +46,8 @@ extends plugins.typedrequestInterfaces.implementsTR<
   request: {
     configData: clusterInterfaces.ICluster;
     services: IService[];
+    platformProviderConfigs?: IPlatformProviderConfig[];
+    platformBindings?: IPlatformBinding[];
   };
   response: {};
 }

package/ts/requests/index.ts

@@ -15,6 +15,7 @@ import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
+import * as platformRequests from './platform.js';
 import * as routingRequests from './routing.js';
 import * as secretBundleRequests from './secretbundle.js';
 import * as secretGroupRequests from './secretgroup.js'; 
@@ -41,6 +42,7 @@ export {
   logRequests as log,
   networkRequests as network,
   nodeRequests as node,
+  platformRequests as platform,
   routingRequests as routing,
   secretBundleRequests as secretbundle,
   secretGroupRequests as secretgroup,
@@ -52,4 +54,4 @@ export {
   versionRequests as version,
 };
 
-export * from './inform.js';
+export * from './inform.js';