@serve.zone/interfaces 19.6.1 → 19.8.0

package/changelog.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2026-07-29 - 19.8.0
+
+### Features
+
+- add an authenticated gateway-client mail-domain count contract (gateway)
+  - Expose getGatewayClientMailDomainCount with a count-only response for distinct configured mail domains.
+  - Derive ownership from the authenticating gateway credential instead of caller-selected owner fields.
+  - Document the new request and extend gateway contract tests.
+
+## 2026-07-29 - 19.7.0
+
+### Features
+
+- add first-class Reply-To support to service mail contracts (mail)
+  - Add optional replyTo support for outbound message payloads as a single bare ASCII mailbox address.
+  - Expose stable mail submission error codes for invalid Reply-To values and typed-field/header conflicts.
+  - Add service-mail type coverage and documentation for Reply-To handling.
+
+### Chores
+
+- update active Git Zone runtime tooling (dev-deps)
+  - Update `@git.zone/tsrun` from 2.0.5 to 2.0.6.
+
 ## 2026-07-28 - 19.6.1
 
 ### Fixes

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '19.6.1',
+    version: '19.8.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

@@ -12,6 +12,7 @@ export type TMailBounceType = 'hard' | 'soft' | 'complaint' | 'unknown';
 export type TMailInboundProtocol = 'smtp' | 'submission' | 'api';
 export type TMailRecipientResolutionAction = 'accept' | 'reject' | 'defer';
 export type TMailDeliveryJournalEventType = 'accepted' | 'queued' | 'deliveryStarted' | 'deliverySucceeded' | 'deliveryDeferred' | 'deliveryFailed' | 'deadLettered' | 'rejected' | 'bounced' | 'complaint';
+export type TMailSubmissionErrorCode = 'INVALID_REPLY_TO' | 'REPLY_TO_FIELD_HEADER_CONFLICT';
 /**
  * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
  * instance, not an App Store template id.
@@ -317,6 +318,8 @@ export interface IMailOutboundMessagePayload {
     to: string[];
     cc?: string[];
     bcc?: string[];
+    /** One bare ASCII mailbox address. Display names and address lists are not supported. */
+    replyTo?: string;
     subject: string;
     text?: string;
     html?: string;

package/dist_ts/requests/gateway.d.ts

@@ -100,6 +100,17 @@ export interface IReq_GetGatewayClientMailOverview extends plugins.typedrequestI
         emails: IMailOverviewEmail[];
     };
 }
+/** Cheap gateway-client-owned count of distinct configured mail domains. */
+export interface IReq_GetGatewayClientMailDomainCount extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientMailDomainCount> {
+    method: 'getGatewayClientMailDomainCount';
+    request: {
+        identity?: IGatewayIdentity;
+        apiToken?: string;
+    };
+    response: {
+        count: number;
+    };
+}
 export interface IReq_GetGatewayClientDomains extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientDomains> {
     method: 'getGatewayClientDomains';
     request: {

package/dist_ts/requests/mail.d.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
-import type { IMailAddressBinding, IMailCredentialOneTimeSecret, IMailConnectionInfo, IMailDeliveryJournalEvent, IMailDeliveryStatus, IMailDomainAuthority, IMailEnvelope, IMailInboundMessagePayload, IMailOutboundIdentity, IMailOutboundMessagePayload, IMailRecipientResolution, IMailResourceOwner, IMailSpoolItem, IWorkAppMailBinding } from '../data/mail.js';
+import type { IMailAddressBinding, IMailCredentialOneTimeSecret, IMailConnectionInfo, IMailDeliveryJournalEvent, IMailDeliveryStatus, IMailDomainAuthority, IMailEnvelope, IMailInboundMessagePayload, IMailOutboundIdentity, IMailOutboundMessagePayload, IMailRecipientResolution, IMailResourceOwner, IMailSpoolItem, IWorkAppMailBinding, TMailSubmissionErrorCode } from '../data/mail.js';
 export interface IMailControlRequestAuth {
     identity?: IIdentity;
     apiToken?: string;
@@ -212,6 +212,7 @@ export interface IReq_EnqueueMail extends plugins.typedrequestInterfaces.impleme
         accepted: boolean;
         spoolItemId?: string;
         outboundIdentity?: IMailOutboundIdentity;
+        errorCode?: TMailSubmissionErrorCode;
         message?: string;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "19.6.1",
+  "version": "19.8.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -17,7 +17,7 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsrun": "^2.0.5",
+    "@git.zone/tsrun": "^2.0.6",
     "@git.zone/tstest": "^3.6.7",
     "@types/node": "^26.1.1"
   },

package/readme.md

@@ -287,7 +287,7 @@ The immutable deployment workflow is:
 
 `data.IServiceDeploymentOperation` is the durable revisioned compare-and-set fence for this workflow. Image promotion requires Cloudly-created trusted evidence that binds the operation, actor, repository, exact tag, root digest, and OCI index media type. The service request group also exposes deployment preflight, exact-digest rollback, retry, and cleanup contracts.
 
-Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned, routeRef-owned, and combined hostname-plus-routeRef routes. A client can label canonical intent with `managedRouteKind: 'letsencrypt-http01-forward'` and set a higher `priority` for a path-specific HTTP-01 route while retaining a separate normal route for the same hostname. Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, `rotateMailCredential`, and `getMailDeliveryStatus`. `IReq_GetMailDeliveryStatus` looks up a delivery spool item by `spoolItemId`, returns `data.IMailDeliveryStatus`, and accepts `IMailSubmissionRequestAuth` so service-mail credentials can query their own accepted, queued, deferred, delivered, or failed status. `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.
+Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned, routeRef-owned, and combined hostname-plus-routeRef routes. A client can label canonical intent with `managedRouteKind: 'letsencrypt-http01-forward'` and set a higher `priority` for a path-specific HTTP-01 route while retaining a separate normal route for the same hostname. Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, `rotateMailCredential`, and `getMailDeliveryStatus`. `IReq_GetMailDeliveryStatus` looks up a delivery spool item by `spoolItemId`, returns `data.IMailDeliveryStatus`, and accepts `IMailSubmissionRequestAuth` so service-mail credentials can query their own accepted, queued, deferred, delivered, or failed status. Typed outbound messages may set `replyTo` to one bare ASCII mailbox address; arbitrary `Reply-To` values do not belong in the custom header bag. Invalid values and typed-field/custom-header conflicts return stable `TMailSubmissionErrorCode` values. `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.
 
 ### Web Push Contracts
 
@@ -345,7 +345,7 @@ const provisioning: requests.gateway.IReq_ProvisionGatewayClientCredential['requ
 };
 ```
 
-`getGatewayClientContext` returns effective live policy. A `gatewayClient` role necessarily includes the credential ID, bound client ID/type, and `policyGeneration`; consumers should reject admin/operator or mismatched contexts rather than falling back to a caller-supplied owner ID. `getGatewayClientMailOverview` provides an owner-scoped domain and recent-message summary. Cloudly therefore uses only `dcrouterGatewayApiToken`; the former `dcrouterOpsApiToken` setting is not part of `data.ICloudlySettings`.
+`getGatewayClientContext` returns effective live policy. A `gatewayClient` role necessarily includes the credential ID, bound client ID/type, and `policyGeneration`; consumers should reject admin/operator or mismatched contexts rather than falling back to a caller-supplied owner ID. `getGatewayClientMailOverview` provides an owner-scoped domain and recent-message summary. `getGatewayClientMailDomainCount` derives ownership exclusively from the authenticating gateway credential and returns `{ count: number }` for its distinct configured mail domains. Cloudly therefore uses only `dcrouterGatewayApiToken`; the former `dcrouterOpsApiToken` setting is not part of `data.ICloudlySettings`.
 
 Request groups are exported by product area:
 

package/ts/00_commitinfo_data.ts

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

package/ts/data/mail.ts

@@ -50,6 +50,10 @@ export type TMailDeliveryJournalEventType =
   | 'bounced'
   | 'complaint';
 
+export type TMailSubmissionErrorCode =
+  | 'INVALID_REPLY_TO'
+  | 'REPLY_TO_FIELD_HEADER_CONFLICT';
+
 /**
  * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
  * instance, not an App Store template id.
@@ -385,6 +389,8 @@ export interface IMailOutboundMessagePayload {
   to: string[];
   cc?: string[];
   bcc?: string[];
+  /** One bare ASCII mailbox address. Display names and address lists are not supported. */
+  replyTo?: string;
   subject: string;
   text?: string;
   html?: string;

package/ts/requests/gateway.ts

@@ -141,6 +141,21 @@ export interface IReq_GetGatewayClientMailOverview extends plugins.typedrequestI
   };
 }
 
+/** Cheap gateway-client-owned count of distinct configured mail domains. */
+export interface IReq_GetGatewayClientMailDomainCount extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientMailDomainCount
+> {
+  method: 'getGatewayClientMailDomainCount';
+  request: {
+    identity?: IGatewayIdentity;
+    apiToken?: string;
+  };
+  response: {
+    count: number;
+  };
+}
+
 export interface IReq_GetGatewayClientDomains extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_GetGatewayClientDomains

package/ts/requests/mail.ts

@@ -15,6 +15,7 @@ import type {
   IMailResourceOwner,
   IMailSpoolItem,
   IWorkAppMailBinding,
+  TMailSubmissionErrorCode,
 } from '../data/mail.js';
 
 export interface IMailControlRequestAuth {
@@ -305,6 +306,7 @@ export interface IReq_EnqueueMail extends plugins.typedrequestInterfaces.impleme
     accepted: boolean;
     spoolItemId?: string;
     outboundIdentity?: IMailOutboundIdentity;
+    errorCode?: TMailSubmissionErrorCode;
     message?: string;
   };
 }