serve.zone/interfaces

Fork 0

Files

T

jkunz d9a3403778 chore(deps): update interface docs tooling

2026-04-28 12:02:15 +00:00

7.8 KiB

Raw Blame History

@serve.zone/interfaces

Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.

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

pnpm add @serve.zone/interfaces

Public API

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

The root export exposes four namespaces:

export {
  data,
  platform,
  platformservice,
  requests,
};

Data Interfaces

Use data when you need durable serve.zone object shapes.

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.

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:

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.

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.

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

pnpm install
pnpm run build
pnpm test

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

7.8 KiB Raw Blame History