@serve.zone/interfaces 5.4.6 → 5.8.0

package/readme.md

@@ -1,22 +1,11 @@
 # @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.
+`@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.
 
-## 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
 
 ```bash
@@ -25,24 +14,24 @@ pnpm add @serve.zone/interfaces
 
 ## Public API
 
+The root export exposes four namespaces:
+
 ```typescript
 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
-export {
-  data,
-  platform,
-  platformservice,
-  requests,
-};
-```
+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 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
 import { data } from '@serve.zone/interfaces';
@@ -78,16 +67,16 @@ const service: data.IService = {
 
 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.
+- `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 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
 import { requests } from '@serve.zone/interfaces';
@@ -97,7 +86,7 @@ type GetClustersRequest = requests.cluster.IReq_Any_Cloudly_GetClusters;
 const methodName: GetClustersRequest['method'] = 'getClusters';
 ```
 
-Each request interface follows the same structure:
+Each request interface follows the same pattern:
 
 ```typescript
 interface IExampleRequest {
@@ -107,10 +96,12 @@ interface IExampleRequest {
 }
 ```
 
-Request groups are exported by domain:
+Request groups are exported by product area:
 
 - `requests.admin`
 - `requests.baremetal`
+- `requests.baseos`
+- `requests.backup`
 - `requests.certificate`
 - `requests.cluster`
 - `requests.config`
@@ -124,6 +115,7 @@ Request groups are exported by domain:
 - `requests.log`
 - `requests.network`
 - `requests.node`
+- `requests.platform`
 - `requests.routing`
 - `requests.secretbundle`
 - `requests.secretgroup`
@@ -136,25 +128,25 @@ Request groups are exported by domain:
 
 ## Platform Contracts
 
-Use `platform` for current product-facing platform APIs.
+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 email sending, recipient registration, status checks, and email stats.
-- `platform.sms` for SMS delivery contracts.
-- `platform.pushnotification` for push-notification contracts.
+- `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` 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.
+- `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
 
@@ -166,33 +158,34 @@ 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
-pnpm install
-pnpm run build
-pnpm test
-```
-
-This package is built with `tsbuild` and tested with `@git.zone/tstest`.
+New code should prefer `platform` unless it must remain compatible with an active legacy consumer.
 
-## Ownership Rules
+## 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 the consuming project until they become real shared contracts.
+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.
-- External SDK-facing interfaces that must remain stable.
+- SDK-facing interfaces that external consumers should be able to rely on.
 
 Poor candidates for this package:
 
-- Private implementation details of a single service.
-- Convenience wrappers with runtime behavior.
-- Backward-compatibility aliases without an active consumer.
+- 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
 
@@ -208,7 +201,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH  
+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.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '5.4.3',
+  version: '5.8.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/backup.ts

@@ -0,0 +1,96 @@
+export type TBackupStatus =
+  | 'pending'
+  | 'running'
+  | 'replicating'
+  | 'replicated'
+  | 'ready'
+  | 'failed'
+  | 'restoring'
+  | 'restored';
+
+export type TBackupTrigger = 'manual' | 'scheduled';
+
+export type TBackupResourceType = 'volume' | 'database' | 'objectstorage';
+
+export interface IBackupSnapshotBase {
+  type: TBackupResourceType;
+  snapshotId: string;
+  snapshotName?: string;
+  originalSize: number;
+  storedSize: number;
+  createdAt: number;
+  tags?: Record<string, string>;
+}
+
+export interface IBackupVolumeSnapshot extends IBackupSnapshotBase {
+  type: 'volume';
+  volumeName: string;
+  mountPath: string;
+}
+
+export interface IBackupDatabaseSnapshot extends IBackupSnapshotBase {
+  type: 'database';
+  resourceName: string;
+  databaseName: string;
+}
+
+export interface IBackupObjectStorageSnapshot extends IBackupSnapshotBase {
+  type: 'objectstorage';
+  resourceName: string;
+  bucketName: string;
+}
+
+export type TBackupSnapshot =
+  | IBackupVolumeSnapshot
+  | IBackupDatabaseSnapshot
+  | IBackupObjectStorageSnapshot;
+
+export type TBackupReplicationTargetType = 's3' | 'smb';
+
+export interface IBackupArchiveObject {
+  path: string;
+  size: number;
+  sha256: string;
+}
+
+export interface IBackupArchiveManifest {
+  version: 1;
+  backupId: string;
+  createdAt: number;
+  objects: IBackupArchiveObject[];
+  totalSize: number;
+}
+
+export interface IBackupReplicationResult {
+  targetType: TBackupReplicationTargetType;
+  targetPath: string;
+  manifestPath: string;
+  manifestSha256: string;
+  objectCount: number;
+  totalSize: number;
+  completedAt: number;
+}
+
+export interface IBackupRestoreEvent {
+  restoredAt: number;
+  status: 'restored' | 'failed';
+  errorText?: string;
+}
+
+export interface IBackupRecord {
+  id: string;
+  serviceId: string;
+  serviceName?: string;
+  clusterId?: string;
+  status: TBackupStatus;
+  trigger: TBackupTrigger;
+  snapshots: TBackupSnapshot[];
+  replication?: IBackupReplicationResult;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  requestedBy?: string;
+  errorText?: string;
+  restoreHistory?: IBackupRestoreEvent[];
+  tags?: Record<string, string>;
+}

package/ts/data/baseos.ts

@@ -0,0 +1,144 @@
+export type TBaseOsRuntimeLevel = 'app-layer' | 'host-os' | 'target-state';
+
+export type TBaseOsCloudlyConnectionStatus =
+  | 'not-configured'
+  | 'connecting'
+  | 'connected'
+  | 'failed';
+
+export interface IBalenaDeviceState {
+  api_port?: number;
+  ip_address?: string;
+  mac_address?: string;
+  commit?: string;
+  status?: string;
+  os_version?: string;
+  supervisor_version?: string;
+  update_pending?: boolean;
+  update_downloaded?: boolean;
+  update_failed?: boolean;
+  download_progress?: number | null;
+  [key: string]: unknown;
+}
+
+export interface IBalenaStateStatus {
+  status?: string;
+  appState?: string;
+  overallDownloadProgress?: number | null;
+  release?: string;
+  containers?: Array<Record<string, unknown>>;
+  images?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+export interface IBaseOsRuntimeInfo {
+  runtime: 'baseos';
+  runtimeLevel: TBaseOsRuntimeLevel;
+  nodeId: string;
+  cloudlyUrl?: string;
+  cloudlyConnectionStatus: TBaseOsCloudlyConnectionStatus;
+  supervisorAvailable: boolean;
+  supervisorAddress?: string;
+  deviceState?: IBalenaDeviceState;
+  stateStatus?: IBalenaStateStatus;
+  checkedAt: number;
+}
+
+export interface IBaseOsDesiredState {
+  release?: string;
+  targetState?: Record<string, unknown>;
+  updatedAt?: number;
+}
+
+export interface IBaseOsNode {
+  id: string;
+  data: {
+    runtimeInfo: IBaseOsRuntimeInfo;
+    desiredState?: IBaseOsDesiredState;
+    createdAt: number;
+    updatedAt: number;
+    lastHeartbeatAt?: number;
+  };
+}
+
+export type TBaseOsImageArchitecture = 'amd64' | 'arm64' | 'rpi';
+export type TBaseOsImageKind = 'ubuntu-iso' | 'balena-raw';
+export type TBaseOsImageSourcePreset =
+  | 'balena-generic-amd64'
+  | 'balena-generic-aarch64'
+  | 'balena-raspberrypi4-64';
+
+export type TBaseOsImageBuildStatus = 'queued' | 'building' | 'ready' | 'failed' | 'cancelled';
+
+export interface IBaseOsWifiConfig {
+  ssid: string;
+  password?: string;
+}
+
+export interface IBaseOsImageArtifact {
+  bucketName: string;
+  key: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  sha256: string;
+  createdAt: number;
+}
+
+export interface IBaseOsImageBuild {
+  id: string;
+  data: {
+    status: TBaseOsImageBuildStatus;
+    architecture: TBaseOsImageArchitecture;
+    imageKind?: TBaseOsImageKind;
+    cloudlyUrl: string;
+    sourceImageUrl?: string;
+    sourceImagePreset?: TBaseOsImageSourcePreset;
+    balenaOsVersion?: string;
+    ubuntuVersion?: string;
+    hostname?: string;
+    wifiSsid?: string;
+    sshPublicKey?: string;
+    artifact?: IBaseOsImageArtifact;
+    errorText?: string;
+    logs: string[];
+    createdAt: number;
+    updatedAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    expiresAt?: number;
+  };
+}
+
+export interface IBaseOsImageBuildRequest {
+  architecture: TBaseOsImageArchitecture;
+  imageKind?: TBaseOsImageKind;
+  cloudlyUrl?: string;
+  sourceImageUrl?: string;
+  sourceImagePreset?: TBaseOsImageSourcePreset;
+  balenaOsVersion?: string;
+  ubuntuVersion?: string;
+  hostname?: string;
+  wifi?: IBaseOsWifiConfig;
+  sshPublicKey?: string;
+  artifactRetentionMs?: number;
+}
+
+export interface IBaseOsImageDownloadUrl {
+  url: string;
+  expiresAt: number;
+}
+
+export interface IBaseOsRegisterResult {
+  nodeId?: string;
+  nodeToken?: string;
+  accepted: boolean;
+  message?: string;
+  desiredState?: IBaseOsDesiredState;
+}
+
+export interface IBaseOsHeartbeatResult {
+  accepted: boolean;
+  message?: string;
+  desiredState?: IBaseOsDesiredState;
+}

package/ts/data/index.ts

@@ -12,6 +12,8 @@ export * from './registry.js';
 export * from './secretbundle.js';
 export * from './secretgroup.js';
 export * from './baremetal.js';
+export * from './baseos.js';
+export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';

package/ts/data/service.ts

@@ -1,6 +1,22 @@
 import type { IServiceRessources } from './docker.js';
 import type { IRegistryTarget } from './registry.js';
 
+export interface IServiceVolume {
+  /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
+  name?: string;
+  /** Alias for name when a volume is shared intentionally across services. */
+  source?: string;
+  /** Container path where the volume is mounted. */
+  mountPath: string;
+  /** Docker volume driver. Defaults to corestore. */
+  driver?: 'corestore' | 'local' | string;
+  readOnly?: boolean;
+  /** Whether backup orchestration should snapshot this volume. Defaults to true. */
+  backup?: boolean;
+  /** Driver-specific options forwarded to Docker's VolumeDriver.Create request. */
+  options?: Record<string, string>;
+}
+
 export interface IService {
   id: string;
   data: {
@@ -55,6 +71,7 @@ export interface IService {
       web: number;
       custom?: { [domain: string]: string };
     };
+    volumes?: IServiceVolume[];
     resources?: IServiceRessources;
     domains: {
       /**

package/ts/data/settings.ts

@@ -8,6 +8,14 @@ export interface ICloudlySettings {
   // Cloud Provider Tokens
   hetznerToken?: string;
   cloudflareToken?: string;
+
+  // BaseOS enrollment
+  baseosJoinToken?: string;
+
+  // CoreBuild worker used for image generation
+  corebuildWorkerUrl?: string;
+  corebuildWorkerToken?: string;
+  corebuildWorkersJson?: string;
   
   // AWS Credentials
   awsAccessKey?: string;
@@ -53,4 +61,4 @@ export interface ICloudlySettings {
  */
 export type ICloudlySettingsMasked = {
   [K in keyof ICloudlySettings]: string | undefined;
-};
+};