@serve.zone/interfaces 7.26.0 → 7.28.0

package/changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026-06-24 - 7.28.0
+
+### Features
+
+- add service mail endpoint registration interfaces (mail)
+  - Add inbound mail configuration fields for typed endpoints and SMTP forwarding targets
+  - Add registerServiceMailEndpoint TypedRequest contract for registering inbound delivery addresses
+
+## 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

package/dist_ts/00_commitinfo_data.js

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

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,38 @@ export interface IWorkAppMailBinding {
     updatedAt: number;
     createdBy?: string;
 }
+export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls';
+export interface IServiceMailInboundConfig {
+    enabled?: boolean;
+    /** Platformclient apps use typedEndpoint; third-party apps with their own SMTP server use smtpForward. */
+    targetType?: 'typedEndpoint' | 'smtpForward';
+    /** TypedRequest method exposed by platformclient over TypedSocket for inbound delivery. */
+    typedMethod?: string;
+    /** 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;
@@ -149,6 +151,18 @@ export interface IReq_DeliverInboundMail extends plugins.typedrequestInterfaces.
         message?: string;
     };
 }
+export interface IReq_RegisterServiceMailEndpoint extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RegisterServiceMailEndpoint> {
+    method: 'registerServiceMailEndpoint';
+    request: {
+        auth: IMailSubmissionRequestAuth;
+        addresses?: string[];
+    };
+    response: {
+        success: boolean;
+        addresses?: string[];
+        message?: string;
+    };
+}
 export interface IReq_GetMailDeliveryStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetMailDeliveryStatus> {
     method: 'getMailDeliveryStatus';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "7.26.0",
+  "version": "7.28.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.26.0',
+  version: '7.28.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

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,43 @@ export interface IWorkAppMailBinding {
   createdBy?: string;
 }
 
+export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls';
+
+export interface IServiceMailInboundConfig {
+  enabled?: boolean;
+  /** Platformclient apps use typedEndpoint; third-party apps with their own SMTP server use smtpForward. */
+  targetType?: 'typedEndpoint' | 'smtpForward';
+  /** TypedRequest method exposed by platformclient over TypedSocket for inbound delivery. */
+  typedMethod?: string;
+  /** 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<
@@ -223,6 +225,22 @@ export interface IReq_DeliverInboundMail extends plugins.typedrequestInterfaces.
   };
 }
 
+export interface IReq_RegisterServiceMailEndpoint extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RegisterServiceMailEndpoint
+> {
+  method: 'registerServiceMailEndpoint';
+  request: {
+    auth: IMailSubmissionRequestAuth;
+    addresses?: string[];
+  };
+  response: {
+    success: boolean;
+    addresses?: string[];
+    message?: string;
+  };
+}
+
 export interface IReq_GetMailDeliveryStatus extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_GetMailDeliveryStatus