@serve.zone/interfaces 8.0.1 → 8.1.0

package/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2026-07-06 - 8.1.0
+
+### Features
+
+- add gateway client route listing contract (gateway)
+  - Add IGatewayClientRoute for client-owned route reconciliation views
+  - Add getGatewayClientRoutes typed request returning gateway client routes
+
+### Fixes
+
+- document gateway client route contracts (docs)
+  - Add README references for IGatewayClientRoute, getGatewayClientRoutes, and syncGatewayClientRoute.
+  - Update the dcrouter gateway settings example to use generic placeholder values.
+
 ## 2026-07-06 - 8.0.1
 
 ### Fixes

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/gateway.d.ts

@@ -229,6 +229,18 @@ export interface IGatewayRouteConfig {
         edgeFilter?: string[];
     };
 }
+/**
+ * Gateway-client-owned route view used for reconciliation by clients.
+ */
+export interface IGatewayClientRoute {
+    id: string;
+    name: string;
+    enabled: boolean;
+    ownership: IGatewayClientOwnership;
+    route: IGatewayRouteConfig;
+    sourceProfileRef?: string;
+    managePath?: string;
+}
 /**
  * Result of an idempotent gateway route sync.
  */

package/dist_ts/requests/gateway.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IGatewayCapabilities, IGatewayClientContext, IGatewayClientOwnership, IGatewayDnsRecord, IGatewayDomain, IGatewayIdentity, IGatewayRouteConfig, IGatewayRouteSyncResult } from '../data/gateway.js';
+import type { IGatewayCapabilities, IGatewayClientContext, IGatewayClientOwnership, IGatewayClientRoute, IGatewayDnsRecord, IGatewayDomain, IGatewayIdentity, IGatewayRouteConfig, IGatewayRouteSyncResult } from '../data/gateway.js';
 /**
  * Gateway client contracts: the machine-facing API a gateway (dcrouter)
  * serves to gateway clients (Onebox, Cloudly/Coreflow).
@@ -53,6 +53,17 @@ export interface IReq_GetGatewayClientDnsRecords extends plugins.typedrequestInt
         records: IGatewayDnsRecord[];
     };
 }
+export interface IReq_GetGatewayClientRoutes extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientRoutes> {
+    method: 'getGatewayClientRoutes';
+    request: {
+        identity?: IGatewayIdentity;
+        apiToken?: string;
+        gatewayClientId?: string;
+    };
+    response: {
+        routes: IGatewayClientRoute[];
+    };
+}
 export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncGatewayClientRoute> {
     method: 'syncGatewayClientRoute';
     request: {

package/package.json

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

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`, gateway route `routeRef` ownership, optional match `domains`, `transport`, and `remoteIngress` route intent.
+- 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.
 - `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.
@@ -138,7 +138,7 @@ 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.
+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`, 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:
 

package/ts/00_commitinfo_data.ts

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

package/ts/data/gateway.ts

@@ -247,6 +247,19 @@ export interface IGatewayRouteConfig {
   };
 }
 
+/**
+ * Gateway-client-owned route view used for reconciliation by clients.
+ */
+export interface IGatewayClientRoute {
+  id: string;
+  name: string;
+  enabled: boolean;
+  ownership: IGatewayClientOwnership;
+  route: IGatewayRouteConfig;
+  sourceProfileRef?: string;
+  managePath?: string;
+}
+
 /**
  * Result of an idempotent gateway route sync.
  */

package/ts/data/settings.ts

@@ -26,7 +26,7 @@ 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"}).
+  // static dcrouterTargetHost (e.g. {"worker-a":"192.0.2.10"}).
   dcrouterGatewayUrl?: string;
   dcrouterGatewayApiToken?: string;
   dcrouterOpsApiToken?: string;

package/ts/requests/gateway.ts

@@ -3,6 +3,7 @@ import type {
   IGatewayCapabilities,
   IGatewayClientContext,
   IGatewayClientOwnership,
+  IGatewayClientRoute,
   IGatewayDnsRecord,
   IGatewayDomain,
   IGatewayIdentity,
@@ -80,6 +81,21 @@ export interface IReq_GetGatewayClientDnsRecords extends plugins.typedrequestInt
   };
 }
 
+export interface IReq_GetGatewayClientRoutes extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientRoutes
+> {
+  method: 'getGatewayClientRoutes';
+  request: {
+    identity?: IGatewayIdentity;
+    apiToken?: string;
+    gatewayClientId?: string;
+  };
+  response: {
+    routes: IGatewayClientRoute[];
+  };
+}
+
 export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_SyncGatewayClientRoute