@serve.zone/interfaces 7.25.0 → 7.27.0

package/changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026-06-22 - 7.27.0
+
+### Features
+
+- add service-level mail configuration contracts (mail)
+  - Expose public outbound credential metadata on mail address bindings and service mail config
+  - Add service data mail configuration for per-address inbound and outbound mail settings
+  - Add dcrouter gateway, SMTP submission, and inbound mail forward settings to Cloudly settings
+  - Add outboundEnabled to mail address binding sync requests
+
+## 2026-06-17 - 7.26.0
+
+### Features
+
+- add node service reconciliation and runtime update interfaces (node)
+  - Add serveZoneServiceUpdate as a supported node action and expose serve.zone service runtime status on node runtime data.
+  - Add typed request contracts for reconciling node base services and pushing node runtime updates.
+
 ## 2026-06-16 - 7.25.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/clusternode.d.ts

@@ -22,7 +22,7 @@ export interface INodeMetricsSample {
     /** Host-level network transmit rate across non-loopback interfaces. */
     networkTxBytesPerSec?: number;
 }
-export type TNodeActionName = 'systemUpgrade' | 'reboot';
+export type TNodeActionName = 'systemUpgrade' | 'reboot' | 'serveZoneServiceUpdate';
 export type TNodeActionStatus = 'pending' | 'running' | 'succeeded' | 'failed';
 /**
  * An operator-requested action executed by spark on a node.
@@ -43,6 +43,19 @@ export interface INodeAction {
     finishedAt?: number;
     resultText?: string;
 }
+export interface IServeZoneServiceRuntimeInfo {
+    name: string;
+    serviceId?: string;
+    image?: string;
+    desiredImage?: string;
+    imageVersion?: string;
+    runningImageId?: string;
+    runningTaskCount?: number;
+    running: boolean;
+    checkedAt: number;
+    updatedAt?: number;
+    error?: string;
+}
 /** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/metrics-sample */
 export interface ISparkMetricsSampleRequest {
     nodeId: string;
@@ -82,6 +95,7 @@ export interface ISparkNodeRuntimeInfo {
     cloudlyConnectionStatus: TSparkCloudlyConnectionStatus;
     dockerAvailable: boolean;
     swarmNodeId?: string;
+    serveZoneServices?: IServeZoneServiceRuntimeInfo[];
     checkedAt: number;
     lastError?: string;
 }

package/dist_ts/data/mail.d.ts

@@ -117,6 +117,8 @@ export interface IMailAddressBinding {
     status: TMailResourceStatus;
     inboundTarget?: IMailInboundTarget;
     outboundIdentityId?: string;
+    /** Public, non-secret credential state for reconciliation. */
+    outboundCredential?: IMailCredentialPublic;
     recipientPolicy?: IMailRecipientPolicy;
     spoolPolicy?: IMailSpoolPolicy;
     createdAt: number;
@@ -169,6 +171,34 @@ export interface IWorkAppMailBinding {
     updatedAt: number;
     createdBy?: string;
 }
+export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls';
+export interface IServiceMailInboundConfig {
+    enabled?: boolean;
+    /** Published Docker/Swarm port that dcrouter may SMTP-forward inbound mail to. */
+    publishedPort?: number;
+    preserveHeaders?: boolean;
+    addHeaders?: Record<string, string>;
+}
+export interface IServiceMailOutboundConfig {
+    enabled?: boolean;
+    /** dcrouter credential id/username. Public metadata only; never store passwords here. */
+    credentialId?: string;
+    username?: string;
+    status?: TMailCredentialStatus;
+    lastRotatedAt?: number;
+}
+export interface IServiceMailAddressConfig {
+    address: string;
+    enabled?: boolean;
+    displayName?: string;
+    inbound?: IServiceMailInboundConfig;
+    outbound?: IServiceMailOutboundConfig;
+}
+export interface IServiceMailConfig {
+    enabled?: boolean;
+    defaultFrom?: string;
+    addresses: IServiceMailAddressConfig[];
+}
 export interface IMailEnvelope {
     mailFrom: string;
     rcptTo: string[];

package/dist_ts/data/service.d.ts

@@ -2,6 +2,7 @@ import type { IServiceRessources } from './docker.js';
 import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
+import type { IServiceMailConfig } from './mail.js';
 export interface IServiceVolume {
     /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
     name?: string;
@@ -114,6 +115,7 @@ export interface IService {
                 [domain: string]: string;
             };
         };
+        mail?: IServiceMailConfig;
         volumes?: IServiceVolume[];
         publishedPorts?: IAppStorePublishedPort[];
         resources?: IServiceRessources;

package/dist_ts/data/settings.d.ts

@@ -9,7 +9,18 @@ export interface ICloudlySettings {
     backupExternalTargetType?: string;
     backupExternalTargetConfig?: string;
     backupNodeCacheKeepDays?: string;
+    dcrouterGatewayUrl?: string;
+    dcrouterGatewayApiToken?: string;
+    dcrouterOpsApiToken?: string;
+    dcrouterGatewayClientId?: string;
+    dcrouterTargetHost?: string;
+    dcrouterTargetPort?: string;
     dcrouterTargetHostsByNode?: string;
+    dcrouterMailSubmissionHost?: string;
+    dcrouterMailSubmissionPort?: string;
+    dcrouterMailSubmissionTlsMode?: 'plain' | 'starttls' | 'implicitTls';
+    dcrouterMailForwardTargetHost?: string;
+    dcrouterMailForwardTargetHostsByNode?: string;
     baseosJoinToken?: string;
     corebuildWorkerUrl?: string;
     corebuildWorkerToken?: string;

package/dist_ts/requests/mail.d.ts

@@ -14,6 +14,8 @@ export type TMailDomainAuthoritySync = Omit<IMailDomainAuthority, 'id' | 'status
 };
 export type TMailAddressBindingSync = Omit<IMailAddressBinding, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
     id?: string;
+    /** Explicitly controls managed SMTP credential availability for this binding. */
+    outboundEnabled?: boolean;
 };
 export type TWorkAppMailBindingSync = Omit<IWorkAppMailBinding, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
     id?: string;

package/dist_ts/requests/node.d.ts

@@ -172,6 +172,19 @@ export interface IReq_Any_Cloudly_GetNodeResourceUsage extends plugins.typedrequ
         timestamp: number;
     };
 }
+export interface IReq_Any_Cloudly_ReconcileNodeBaseServices extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_ReconcileNodeBaseServices> {
+    method: 'reconcileNodeBaseServices';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+    };
+    response: {
+        nodeId: string;
+        nodeName: string;
+        success: boolean;
+        message?: string;
+    };
+}
 /**
  * Cloudly asks a node's coreflow for live per-deployment resource usage.
  */
@@ -204,3 +217,10 @@ export interface IReq_Cloudly_Any_PushNodeActionUpdate extends plugins.typedrequ
     };
     response: Record<string, never>;
 }
+export interface IReq_Cloudly_Any_PushNodeRuntimeUpdate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Any_PushNodeRuntimeUpdate> {
+    method: 'pushNodeRuntimeUpdate';
+    request: {
+        node: IClusterNode;
+    };
+    response: Record<string, never>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "7.25.0",
+  "version": "7.27.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -72,7 +72,8 @@ Common data contracts include:
 - `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.
-- Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, credentials, spool items, delivery journals, and inbound/outbound message payloads.
+- Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
+- Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
 - `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.
 
@@ -98,6 +99,8 @@ interface IExampleRequest {
 }
 ```
 
+Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, and `rotateMailCredential`. `TMailAddressBindingSync.outboundEnabled` explicitly controls whether a gateway should maintain a managed outbound SMTP credential for an address binding. Binding credential metadata is public; `rotateMailCredential` returns the new secret only in its one-time `IMailCredentialOneTimeSecret` response.
+
 Request groups are exported by product area:
 
 - `requests.admin`

package/ts/00_commitinfo_data.ts

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

package/ts/data/clusternode.ts

@@ -25,7 +25,7 @@ export interface INodeMetricsSample {
   networkTxBytesPerSec?: number;
 }
 
-export type TNodeActionName = 'systemUpgrade' | 'reboot';
+export type TNodeActionName = 'systemUpgrade' | 'reboot' | 'serveZoneServiceUpdate';
 
 export type TNodeActionStatus = 'pending' | 'running' | 'succeeded' | 'failed';
 
@@ -49,6 +49,20 @@ export interface INodeAction {
   resultText?: string;
 }
 
+export interface IServeZoneServiceRuntimeInfo {
+  name: string;
+  serviceId?: string;
+  image?: string;
+  desiredImage?: string;
+  imageVersion?: string;
+  runningImageId?: string;
+  runningTaskCount?: number;
+  running: boolean;
+  checkedAt: number;
+  updatedAt?: number;
+  error?: string;
+}
+
 /** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/metrics-sample */
 export interface ISparkMetricsSampleRequest {
   nodeId: string;
@@ -98,6 +112,7 @@ export interface ISparkNodeRuntimeInfo {
   cloudlyConnectionStatus: TSparkCloudlyConnectionStatus;
   dockerAvailable: boolean;
   swarmNodeId?: string;
+  serveZoneServices?: IServeZoneServiceRuntimeInfo[];
   checkedAt: number;
   lastError?: string;
 }

package/ts/data/mail.ts

@@ -166,6 +166,8 @@ export interface IMailAddressBinding {
   status: TMailResourceStatus;
   inboundTarget?: IMailInboundTarget;
   outboundIdentityId?: string;
+  /** Public, non-secret credential state for reconciliation. */
+  outboundCredential?: IMailCredentialPublic;
   recipientPolicy?: IMailRecipientPolicy;
   spoolPolicy?: IMailSpoolPolicy;
   createdAt: number;
@@ -221,6 +223,39 @@ export interface IWorkAppMailBinding {
   createdBy?: string;
 }
 
+export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls';
+
+export interface IServiceMailInboundConfig {
+  enabled?: boolean;
+  /** Published Docker/Swarm port that dcrouter may SMTP-forward inbound mail to. */
+  publishedPort?: number;
+  preserveHeaders?: boolean;
+  addHeaders?: Record<string, string>;
+}
+
+export interface IServiceMailOutboundConfig {
+  enabled?: boolean;
+  /** dcrouter credential id/username. Public metadata only; never store passwords here. */
+  credentialId?: string;
+  username?: string;
+  status?: TMailCredentialStatus;
+  lastRotatedAt?: number;
+}
+
+export interface IServiceMailAddressConfig {
+  address: string;
+  enabled?: boolean;
+  displayName?: string;
+  inbound?: IServiceMailInboundConfig;
+  outbound?: IServiceMailOutboundConfig;
+}
+
+export interface IServiceMailConfig {
+  enabled?: boolean;
+  defaultFrom?: string;
+  addresses: IServiceMailAddressConfig[];
+}
+
 export interface IMailEnvelope {
   mailFrom: string;
   rcptTo: string[];

package/ts/data/service.ts

@@ -2,6 +2,7 @@ import type { IServiceRessources } from './docker.js';
 import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
+import type { IServiceMailConfig } from './mail.js';
 
 export interface IServiceVolume {
   /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -122,6 +123,7 @@ export interface IService {
       web: number;
       custom?: { [domain: string]: string };
     };
+    mail?: IServiceMailConfig;
     volumes?: IServiceVolume[];
     publishedPorts?: IAppStorePublishedPort[];
     resources?: IServiceRessources;

package/ts/data/settings.ts

@@ -27,8 +27,22 @@ export interface ICloudlySettings {
   // JSON map of swarm node hostname -> gateway-reachable IP/host. Routes for
   // services pinned to a node target that node's coretraffic instead of the
   // static dcrouterTargetHost (e.g. {"cloudlyworkergrasberg":"192.168.190.108"}).
+  dcrouterGatewayUrl?: string;
+  dcrouterGatewayApiToken?: string;
+  dcrouterOpsApiToken?: string;
+  dcrouterGatewayClientId?: string;
+  dcrouterTargetHost?: string;
+  dcrouterTargetPort?: string;
   dcrouterTargetHostsByNode?: string;
 
+  // External dcrouter mail integration. Submission settings are injected into
+  // service secret bundles; forward targets are used for inbound smtpForward.
+  dcrouterMailSubmissionHost?: string;
+  dcrouterMailSubmissionPort?: string;
+  dcrouterMailSubmissionTlsMode?: 'plain' | 'starttls' | 'implicitTls';
+  dcrouterMailForwardTargetHost?: string;
+  dcrouterMailForwardTargetHostsByNode?: string;
+
   // BaseOS enrollment
   baseosJoinToken?: string;
 

package/ts/requests/mail.ts

@@ -39,6 +39,8 @@ export type TMailAddressBindingSync = Omit<
   'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'
 > & {
   id?: string;
+  /** Explicitly controls managed SMTP credential availability for this binding. */
+  outboundEnabled?: boolean;
 };
 
 export type TWorkAppMailBindingSync = Omit<

package/ts/requests/node.ts

@@ -217,6 +217,23 @@ export interface IReq_Any_Cloudly_GetNodeResourceUsage extends plugins.typedrequ
   };
 }
 
+export interface IReq_Any_Cloudly_ReconcileNodeBaseServices extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_ReconcileNodeBaseServices
+> {
+  method: 'reconcileNodeBaseServices';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+  };
+  response: {
+    nodeId: string;
+    nodeName: string;
+    success: boolean;
+    message?: string;
+  };
+}
+
 /**
  * Cloudly asks a node's coreflow for live per-deployment resource usage.
  */
@@ -260,3 +277,14 @@ export interface IReq_Cloudly_Any_PushNodeActionUpdate extends plugins.typedrequ
   };
   response: Record<string, never>;
 }
+
+export interface IReq_Cloudly_Any_PushNodeRuntimeUpdate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Any_PushNodeRuntimeUpdate
+> {
+  method: 'pushNodeRuntimeUpdate';
+  request: {
+    node: IClusterNode;
+  };
+  response: Record<string, never>;
+}