interfaces/readme.md

# @serve.zone/interfaces

`@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.

## 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.

## Install

```bash
pnpm add @serve.zone/interfaces
```

## Public API

The root export exposes four namespaces:

```typescript
import { data, platform, platformservice, requests } from '@serve.zone/interfaces';
```

| 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. |

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.

## Data Contracts

Use `data` when you need object shapes that are persisted, exchanged between services, or exposed through the Cloudly API.

```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 state.
- `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
- `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
- `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
- `IUser`, `IIdentity`, and token-related contracts for authentication context.
- `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.

## TypedRequest Contracts

Use `requests` when registering handlers with `@api.global/typedrequest` or when creating typed requests through a TypedSocket client.

```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 pattern:

```typescript
interface IExampleRequest {
  method: 'methodName';
  request: Record<string, unknown>;
  response: Record<string, unknown>;
}
```

Request groups are exported by product area:

- `requests.admin`
- `requests.baremetal`
- `requests.baseos`
- `requests.backup`
- `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.platform`
- `requests.routing`
- `requests.secretbundle`
- `requests.secretgroup`
- `requests.server`
- `requests.service`
- `requests.settings`
- `requests.status`
- `requests.task`
- `requests.version`

## Platform Contracts

Use `platform` for current platform-service capabilities and application-facing platform RPCs.

```typescript
import { platform } from '@serve.zone/interfaces';

type SendEmailRequest = platform.email.IReq_SendEmail;
type PlatformBinding = platform.IPlatformBinding;

const sendEmailMethod: SendEmailRequest['method'] = 'sendEmail';
```

Available platform modules:

- `platform.email` for transactional email, recipient registration, email status, and email stats.
- `platform.sms` for SMS delivery and verification-code delivery.
- `platform.pushnotification` for push-notification delivery.
- `platform.letter` for physical letter workflows.
- `platform.ai`, `platform.database`, `platform.objectstorage`, `platform.logging`, `platform.backup`, and `platform.sip` for infrastructure and application capabilities.
- `platform.types` plus root re-exports for shared capability, provider, binding, credential, and endpoint 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 `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

```bash
pnpm install
pnpm run build
pnpm test
pnpm run buildDocs
```

The package is authored as ESM TypeScript and built with `tsbuild tsfolders --allowimplicitany`.

## 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.