chore(deps): update interface docs tooling
This commit is contained in:
@@ -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, requests, platformservice } from '@serve.zone/interfaces';
|
||||
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 } 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`.
|
||||
|
||||
Only ecosystem-wide public contracts belong here. Cloudly-internal implementation types should stay in Cloudly.
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user