@serve.zone/interfaces 5.9.0 → 5.10.0

package/changelog.md

@@ -3,6 +3,18 @@
 ## Pending
 
 
+## 2026-05-24 - 5.10.0
+
+### Features
+
+- add Spark node telemetry contracts
+  - Adds Spark runtime status fields to cluster node data
+  - Adds a typed Spark-to-Cloudly heartbeat request contract
+
+### Maintenance
+
+- refresh release tooling dependencies
+
 ## 2026-05-23 - 5.9.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '5.9.0',
+    version: '5.10.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/appcatalog/types.d.ts

@@ -21,6 +21,14 @@ export interface IAppCatalogVolume {
     options?: Record<string, string>;
 }
 export type TAppCatalogVolumeSpec = string | IAppCatalogVolume;
+export interface IAppCatalogPublishedPort {
+    targetPort: number;
+    targetPortEnd?: number;
+    publishedPort?: number;
+    publishedPortEnd?: number;
+    protocol?: 'tcp' | 'udp';
+    hostIp?: string;
+}
 export interface ICatalogApp {
     id: string;
     name: string;
@@ -52,6 +60,7 @@ export interface IAppVersionConfig {
     port: number;
     envVars?: IAppCatalogEnvVar[];
     volumes?: TAppCatalogVolumeSpec[];
+    publishedPorts?: IAppCatalogPublishedPort[];
     platformRequirements?: Partial<Record<TAppCatalogPlatformRequirement, boolean>>;
     minOneboxVersion?: string;
     minCloudlyVersion?: string;
@@ -62,6 +71,7 @@ export interface IAppInstallRequest {
     serviceName: string;
     domain?: string;
     port?: number;
+    publishedPorts?: IAppCatalogPublishedPort[];
     envVars?: Record<string, string>;
 }
 export interface IUpgradeableAppService {

package/dist_ts/data/clusternode.d.ts

@@ -8,6 +8,24 @@ export interface IClusterNodeMetrics {
     containerCount: number;
     timestamp: number;
 }
+export type TSparkNodeMode = 'cloudly' | 'coreflow-node';
+export type TSparkCloudlyConnectionStatus = 'not-configured' | 'connecting' | 'connected' | 'failed';
+export interface ISparkNodeRuntimeInfo {
+    runtime: 'spark';
+    nodeId: string;
+    mode?: TSparkNodeMode;
+    hostname?: string;
+    platform: string;
+    arch: string;
+    osRelease?: string;
+    sparkVersion: string;
+    cloudlyUrl?: string;
+    cloudlyConnectionStatus: TSparkCloudlyConnectionStatus;
+    dockerAvailable: boolean;
+    swarmNodeId?: string;
+    checkedAt: number;
+    lastError?: string;
+}
 export interface IClusterNode {
     id: string;
     data: {
@@ -43,6 +61,10 @@ export interface IClusterNode {
          * Current metrics for the node
          */
         metrics?: IClusterNodeMetrics;
+        /**
+         * Runtime status reported by the Spark node agent.
+         */
+        sparkRuntimeInfo?: ISparkNodeRuntimeInfo;
         /**
          * Docker swarm node ID if part of swarm
          */

package/dist_ts/requests/node.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IClusterNode } from '../data/clusternode.js';
+import type { IClusterNode, IClusterNodeMetrics, ISparkNodeRuntimeInfo } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
 export interface IRequest_Any_Cloudly_GetNodeConfig {
@@ -46,3 +46,16 @@ export interface IReq_Any_Cloudly_CreateNodeJumpCommand extends plugins.typedreq
         expiresAt: number;
     };
 }
+export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Spark_Cloudly_SendHeartbeat> {
+    method: 'sparkNodeHeartbeat';
+    request: {
+        nodeId: string;
+        nodeToken: string;
+        metrics: IClusterNodeMetrics;
+        runtimeInfo: ISparkNodeRuntimeInfo;
+    };
+    response: {
+        accepted: boolean;
+        message?: string;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -15,11 +15,11 @@
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsdoc": "^2.0.3",
-    "@git.zone/tsrun": "^2.0.3",
-    "@git.zone/tstest": "^3.6.3",
-    "@types/node": "^25.6.1"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsdoc": "^2.0.6",
+    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tstest": "^3.6.6",
+    "@types/node": "^25.8.0"
   },
   "files": [
     "ts/**/*",

package/ts/00_commitinfo_data.ts

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

package/ts/appcatalog/types.ts

@@ -25,6 +25,15 @@ export interface IAppCatalogVolume {
 
 export type TAppCatalogVolumeSpec = string | IAppCatalogVolume;
 
+export interface IAppCatalogPublishedPort {
+  targetPort: number;
+  targetPortEnd?: number;
+  publishedPort?: number;
+  publishedPortEnd?: number;
+  protocol?: 'tcp' | 'udp';
+  hostIp?: string;
+}
+
 export interface ICatalogApp {
   id: string;
   name: string;
@@ -59,6 +68,7 @@ export interface IAppVersionConfig {
   port: number;
   envVars?: IAppCatalogEnvVar[];
   volumes?: TAppCatalogVolumeSpec[];
+  publishedPorts?: IAppCatalogPublishedPort[];
   platformRequirements?: Partial<Record<TAppCatalogPlatformRequirement, boolean>>;
   minOneboxVersion?: string;
   minCloudlyVersion?: string;
@@ -70,6 +80,7 @@ export interface IAppInstallRequest {
   serviceName: string;
   domain?: string;
   port?: number;
+  publishedPorts?: IAppCatalogPublishedPort[];
   envVars?: Record<string, string>;
 }
 

package/ts/data/clusternode.ts

@@ -10,6 +10,31 @@ export interface IClusterNodeMetrics {
   timestamp: number;
 }
 
+export type TSparkNodeMode = 'cloudly' | 'coreflow-node';
+
+export type TSparkCloudlyConnectionStatus =
+  | 'not-configured'
+  | 'connecting'
+  | 'connected'
+  | 'failed';
+
+export interface ISparkNodeRuntimeInfo {
+  runtime: 'spark';
+  nodeId: string;
+  mode?: TSparkNodeMode;
+  hostname?: string;
+  platform: string;
+  arch: string;
+  osRelease?: string;
+  sparkVersion: string;
+  cloudlyUrl?: string;
+  cloudlyConnectionStatus: TSparkCloudlyConnectionStatus;
+  dockerAvailable: boolean;
+  swarmNodeId?: string;
+  checkedAt: number;
+  lastError?: string;
+}
+
 export interface IClusterNode {
   id: string;
   data: {
@@ -52,6 +77,11 @@ export interface IClusterNode {
      * Current metrics for the node
      */
     metrics?: IClusterNodeMetrics;
+
+    /**
+     * Runtime status reported by the Spark node agent.
+     */
+    sparkRuntimeInfo?: ISparkNodeRuntimeInfo;
     
     /**
      * Docker swarm node ID if part of swarm
@@ -68,4 +98,4 @@ export interface IClusterNode {
      */
     requiredDebianPackages: string[];
   };
-}
+}

package/ts/requests/node.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IClusterNode } from '../data/clusternode.js';
+import type { IClusterNode, IClusterNodeMetrics, ISparkNodeRuntimeInfo } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
 
@@ -53,3 +53,20 @@ export interface IReq_Any_Cloudly_CreateNodeJumpCommand extends plugins.typedreq
     expiresAt: number;
   };
 }
+
+export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Spark_Cloudly_SendHeartbeat
+> {
+  method: 'sparkNodeHeartbeat';
+  request: {
+    nodeId: string;
+    nodeToken: string;
+    metrics: IClusterNodeMetrics;
+    runtimeInfo: ISparkNodeRuntimeInfo;
+  };
+  response: {
+    accepted: boolean;
+    message?: string;
+  };
+}