@serve.zone/interfaces 11.1.1 → 11.2.0

package/changelog.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2026-07-15 - 11.2.0
+
+### Features
+
+- Support priority and managed-kind metadata on gateway routes.
+  - Allow combined `hostname` plus `routeRef` ownership so multiple managed routes for one hostname reconcile independently.
+  - Define the canonical `letsencrypt-http01-forward` managed route kind.
+
+### Maintenance
+
+- Update the release toolchain to pnpm 11.13.0 and Node.js types 26.1.1.
+
 ## 2026-07-13 - 11.1.1
 
 ### Fixes

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/gateway.d.ts

@@ -3,6 +3,10 @@ import type { TDnsRecordType } from './dns.js';
  * Type of platform acting as a gateway client against a gateway (dcrouter).
  */
 export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
+/**
+ * Canonical managed route purposes understood by gateways.
+ */
+export type TManagedRouteKind = 'letsencrypt-http01-forward';
 /**
  * Identity attached to gateway requests. Gateways run their own user/auth
  * domain (e.g. dcrouter operator accounts), so role/type stay open strings;
@@ -175,7 +179,11 @@ export interface IGatewayClientOwnership {
     appId: string;
     /** Hostname ownership for domain routes. Preserved for existing route keys. */
     hostname?: string;
-    /** Stable non-domain route key, for example public-port mapping exposure refs. */
+    /**
+     * Stable route key. Without hostname it identifies a non-domain route such as
+     * a public-port mapping. Together with hostname it distinguishes multiple
+     * managed routes for the same hostname.
+     */
     routeRef?: string;
 }
 /**
@@ -224,6 +232,10 @@ export interface IGatewayRouteConfig {
     name: string;
     match: IGatewayRouteMatch;
     action: IGatewayRouteAction;
+    /** Higher values are matched first by the gateway. */
+    priority?: number;
+    /** Declares a canonical gateway-managed route purpose. */
+    managedRouteKind?: TManagedRouteKind;
     remoteIngress?: {
         enabled: boolean;
         edgeFilter?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "11.1.1",
+  "version": "11.2.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -19,7 +19,7 @@
     "@git.zone/tsdoc": "^2.1.1",
     "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^26.1.0"
+    "@types/node": "^26.1.1"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -95,7 +95,7 @@ Common data contracts include:
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
-- Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, `IGatewayClientRoute` client-owned route views, gateway route `routeRef` ownership, optional match `domains`, `transport`, and `remoteIngress` route intent.
+- Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, and `IGatewayClientRoute` client-owned route views. Gateway route intent supports optional match `domains`, `transport`, and `remoteIngress`, plus explicit route `priority` and `managedRouteKind`. Ownership can combine `hostname` with `routeRef` so a normal route and a path-specific managed route for the same hostname reconcile independently.
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
 - 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.
@@ -140,7 +140,7 @@ interface IExampleRequest {
 
 `requests.config.IRequest_Any_Cloudly_GetClusterConfig` accepts `data.IIdentityCredential`, which contains only the JWT needed for server-side identity resolution. Username/password login and machine-token exchange responses continue to return the full `data.IIdentity`.
 
-Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned and routeRef-owned routes. 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. `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:
 

package/ts/00_commitinfo_data.ts

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

package/ts/data/gateway.ts

@@ -5,6 +5,11 @@ import type { TDnsRecordType } from './dns.js';
  */
 export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
 
+/**
+ * Canonical managed route purposes understood by gateways.
+ */
+export type TManagedRouteKind = 'letsencrypt-http01-forward';
+
 /**
  * Identity attached to gateway requests. Gateways run their own user/auth
  * domain (e.g. dcrouter operator accounts), so role/type stay open strings;
@@ -187,7 +192,11 @@ export interface IGatewayClientOwnership {
   appId: string;
   /** Hostname ownership for domain routes. Preserved for existing route keys. */
   hostname?: string;
-  /** Stable non-domain route key, for example public-port mapping exposure refs. */
+  /**
+   * Stable route key. Without hostname it identifies a non-domain route such as
+   * a public-port mapping. Together with hostname it distinguishes multiple
+   * managed routes for the same hostname.
+   */
   routeRef?: string;
 }
 
@@ -241,6 +250,10 @@ export interface IGatewayRouteConfig {
   name: string;
   match: IGatewayRouteMatch;
   action: IGatewayRouteAction;
+  /** Higher values are matched first by the gateway. */
+  priority?: number;
+  /** Declares a canonical gateway-managed route purpose. */
+  managedRouteKind?: TManagedRouteKind;
   remoteIngress?: {
     enabled: boolean;
     edgeFilter?: string[];