serve.zone/interfaces
3
0
Fork 0
Code Issues Pull Requests Actions 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 4464093d3d
commit 55012a0842
1 changed files with 51 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+51 -58
View File
@@ -1,22 +1,11 @@
# @serve.zone/interfaces # @serve.zone/interfaces
Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem. `@serve.zone/interfaces` is the shared TypeScript contract package for the serve.zone ecosystem. It contains the public data shapes and TypedRequest interfaces used by Cloudly, Coreflow, Spark, Coretraffic, platform clients, SDKs, and external integrations to exchange infrastructure state without duplicating DTOs.
`@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 ## 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.
## 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 ## Install
```bash ```bash
@@ -25,24 +14,24 @@ pnpm add @serve.zone/interfaces
## Public API ## Public API
The root export exposes four namespaces:
```typescript ```typescript
import { data, platform, platformservice, requests } from '@serve.zone/interfaces'; import { data, platform, platformservice, requests } from '@serve.zone/interfaces';
``` ```
The root export exposes four namespaces: | Namespace | Purpose |
| --- | --- |
| `data` | Durable platform object shapes such as clusters, services, deployments, images, domains, DNS entries, secrets, users, status, settings, backups, registries, BaseOS metadata, and task executions. |
| `requests` | TypedRequest contracts for Cloudly and serve.zone control-plane RPC methods. |
| `platform` | Current platform-service contracts for email, SMS, push notifications, letters, AI, databases, object storage, logging, backups, and SIP. |
| `platformservice` | Legacy platform-service namespace kept for older consumers that still depend on the previous layout. |
```typescript This package intentionally has no service implementation logic. It is a stable vocabulary for services that need to agree on payload shape, method names, and response types.
export {
data,
platform,
platformservice,
requests,
};
```
## Data Interfaces ## Data Contracts
Use `data` when you need durable serve.zone object shapes. Use `data` when you need object shapes that are persisted, exchanged between services, or exposed through the Cloudly API.
```typescript ```typescript
import { data } from '@serve.zone/interfaces'; import { data } from '@serve.zone/interfaces';
@@ -78,16 +67,16 @@ const service: data.IService = {
Common data contracts include: Common data contracts include:
- `ICluster` and `IClusterNode` for cluster membership and provisioning metadata. - `ICluster` and `IClusterNode` for cluster membership and provisioning state.
- `IService`, `IDeployment`, and `IImage` for workload configuration and deployment state. - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
- `IDnsEntry`, `IDomain`, and traffic interfaces for routing and domain management. - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
- `ISecretBundle` and `ISecretGroup` for secret ownership and grouping. - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
- `IUser`, `IIdentity`, and token-related interfaces for authentication context. - `IUser`, `IIdentity`, and token-related contracts for authentication context.
- `ICloudlyConfig`, settings, status, server, bare-metal, and task execution interfaces for control-plane state. - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
## TypedRequest Contracts ## TypedRequest Contracts
Use `requests` when registering handlers or creating typed clients with `@api.global/typedrequest` or `@api.global/typedsocket`. Use `requests` when registering handlers with `@api.global/typedrequest` or when creating typed requests through a TypedSocket client.
```typescript ```typescript
import { requests } from '@serve.zone/interfaces'; import { requests } from '@serve.zone/interfaces';
@@ -97,7 +86,7 @@ type GetClustersRequest = requests.cluster.IReq_Any_Cloudly_GetClusters;
const methodName: GetClustersRequest['method'] = 'getClusters'; const methodName: GetClustersRequest['method'] = 'getClusters';
``` ```
Each request interface follows the same structure: Each request interface follows the same pattern:
```typescript ```typescript
interface IExampleRequest { interface IExampleRequest {
@@ -107,10 +96,12 @@ interface IExampleRequest {
} }
``` ```
Request groups are exported by domain: Request groups are exported by product area:
- `requests.admin` - `requests.admin`
- `requests.baremetal` - `requests.baremetal`
- `requests.baseos`
- `requests.backup`
- `requests.certificate` - `requests.certificate`
- `requests.cluster` - `requests.cluster`
- `requests.config` - `requests.config`
@@ -124,6 +115,7 @@ Request groups are exported by domain:
- `requests.log` - `requests.log`
- `requests.network` - `requests.network`
- `requests.node` - `requests.node`
- `requests.platform`
- `requests.routing` - `requests.routing`
- `requests.secretbundle` - `requests.secretbundle`
- `requests.secretgroup` - `requests.secretgroup`
@@ -136,25 +128,25 @@ Request groups are exported by domain:
## Platform Contracts ## Platform Contracts
Use `platform` for current product-facing platform APIs. Use `platform` for current platform-service capabilities and application-facing platform RPCs.
```typescript ```typescript
import { platform } from '@serve.zone/interfaces'; import { platform } from '@serve.zone/interfaces';
type SendEmailRequest = platform.email.IReq_SendEmail; type SendEmailRequest = platform.email.IReq_SendEmail;
type PlatformBinding = platform.IPlatformBinding;
const sendEmailMethod: SendEmailRequest['method'] = 'sendEmail'; const sendEmailMethod: SendEmailRequest['method'] = 'sendEmail';
``` ```
Available platform modules: Available platform modules:
- `platform.email` for email sending, recipient registration, status checks, and email stats. - `platform.email` for transactional email, recipient registration, email status, and email stats.
- `platform.sms` for SMS delivery contracts. - `platform.sms` for SMS delivery and verification-code delivery.
- `platform.pushnotification` for push-notification contracts. - `platform.pushnotification` for push-notification delivery.
- `platform.letter` for physical letter workflows. - `platform.letter` for physical letter workflows.
- `platform.ai` for AI bridge contracts. - `platform.ai`, `platform.database`, `platform.objectstorage`, `platform.logging`, `platform.backup`, and `platform.sip` for infrastructure and application capabilities.
- `platform.backup`, `platform.database`, `platform.logging`, `platform.objectstorage`, and `platform.sip` for infrastructure-facing platform features. - `platform.types` plus root re-exports for shared capability, provider, binding, credential, and endpoint metadata.
- `platform.types` for shared platform service metadata.
## Legacy Platformservice Contracts ## Legacy Platformservice Contracts
@@ -166,7 +158,23 @@ import { platformservice } from '@serve.zone/interfaces';
type LegacySendEmailRequest = platformservice.mta.IRequest_SendEmail; type LegacySendEmailRequest = platformservice.mta.IRequest_SendEmail;
``` ```
New code should prefer the `platform` namespace unless it must remain compatible with an existing platformservice consumer. New code should prefer `platform` unless it must remain compatible with an active legacy consumer.
## Contract Ownership
Only ecosystem-wide public contracts belong in this package. Cloudly-internal implementation details, service-private DTOs, and temporary migration helpers should stay in their owning service 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.
- SDK-facing interfaces that external consumers should be able to rely on.
Poor candidates for this package:
- Private implementation details of one service.
- Runtime helpers or convenience wrappers.
- Compatibility aliases without an active consumer.
## Development ## Development
@@ -174,25 +182,10 @@ New code should prefer the `platform` namespace unless it must remain compatible
pnpm install pnpm install
pnpm run build pnpm run build
pnpm test pnpm test
pnpm run buildDocs
``` ```
This package is built with `tsbuild` and tested with `@git.zone/tstest`. The package is authored as ESM TypeScript and built with `tsbuild tsfolders --allowimplicitany`.
## 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 ## License and Legal Information
@@ -208,7 +201,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.