@serve.zone/interfaces 7.15.0 → 7.16.0

package/changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-06-10 - 7.16.0
+
+### Features
+
+- add archive pruning and external backup tier interfaces (backup)
+  - Add backup record metadata for cache/external tiers and offload timestamps
+  - Define archive retention/prune result interfaces and coreflowPruneNodeArchive typed request
+  - Add settings for external backup targets and node cache retention
+
 ## 2026-06-10 - 7.15.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/backup.d.ts

@@ -62,6 +62,14 @@ export interface IBackupRecord {
     trigger: TBackupTrigger;
     snapshots: TBackupSnapshot[];
     replication?: IBackupReplicationResult;
+    /**
+     * Storage tier of the replicated archive: 'cache' = the platform S3
+     * binding next to cloudly; 'external' = the configured long-term target
+     * (external S3, NFS path, SMB). Offload moves cache -> external and then
+     * deletes the cache copy.
+     */
+    tier?: 'cache' | 'external';
+    offloadedAt?: number;
     createdAt: number;
     updatedAt: number;
     completedAt?: number;
@@ -70,3 +78,17 @@ export interface IBackupRecord {
     restoreHistory?: IBackupRestoreEvent[];
     tags?: Record<string, string>;
 }
+/** Retention policy understood by containerarchive prune. */
+export interface IArchiveRetentionPolicy {
+    keepLast?: number;
+    keepDays?: number;
+    keepWeeks?: number;
+    keepMonths?: number;
+}
+export interface IArchivePruneResult {
+    removedSnapshots: number;
+    removedPacks: number;
+    rewrittenPacks: number;
+    freedBytes: number;
+    dryRun: boolean;
+}

package/dist_ts/data/settings.d.ts

@@ -6,6 +6,9 @@ export interface ICloudlySettings {
     hetznerToken?: string;
     cloudflareToken?: string;
     deploymentArchiveRetentionDays?: string;
+    backupExternalTargetType?: string;
+    backupExternalTargetConfig?: string;
+    backupNodeCacheKeepDays?: string;
     baseosJoinToken?: string;
     corebuildWorkerUrl?: string;
     corebuildWorkerToken?: string;

package/dist_ts/requests/backup.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, TBackupSnapshot } from '../data/backup.js';
+import type { IArchivePruneResult, IArchiveRetentionPolicy, IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, TBackupSnapshot } from '../data/backup.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
 export interface IReq_Any_Cloudly_CreateServiceBackup extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateServiceBackup> {
@@ -135,3 +135,14 @@ export interface IReq_Coreflow_Cloudly_DownloadBackupArchiveObject extends plugi
         contentsBase64: string;
     };
 }
+export interface IReq_Cloudly_Coreflow_PruneNodeArchive extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_PruneNodeArchive> {
+    method: 'coreflowPruneNodeArchive';
+    request: {
+        retention: IArchiveRetentionPolicy;
+        dryRun?: boolean;
+    };
+    response: {
+        found: boolean;
+        result?: IArchivePruneResult;
+    };
+}

package/package.json

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

package/ts/00_commitinfo_data.ts

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

package/ts/data/backup.ts

@@ -86,6 +86,14 @@ export interface IBackupRecord {
   trigger: TBackupTrigger;
   snapshots: TBackupSnapshot[];
   replication?: IBackupReplicationResult;
+  /**
+   * Storage tier of the replicated archive: 'cache' = the platform S3
+   * binding next to cloudly; 'external' = the configured long-term target
+   * (external S3, NFS path, SMB). Offload moves cache -> external and then
+   * deletes the cache copy.
+   */
+  tier?: 'cache' | 'external';
+  offloadedAt?: number;
   createdAt: number;
   updatedAt: number;
   completedAt?: number;
@@ -94,3 +102,19 @@ export interface IBackupRecord {
   restoreHistory?: IBackupRestoreEvent[];
   tags?: Record<string, string>;
 }
+
+/** Retention policy understood by containerarchive prune. */
+export interface IArchiveRetentionPolicy {
+  keepLast?: number;
+  keepDays?: number;
+  keepWeeks?: number;
+  keepMonths?: number;
+}
+
+export interface IArchivePruneResult {
+  removedSnapshots: number;
+  removedPacks: number;
+  rewrittenPacks: number;
+  freedBytes: number;
+  dryRun: boolean;
+}

package/ts/data/settings.ts

@@ -12,6 +12,18 @@ export interface ICloudlySettings {
   // Retention for archived deployment records in days (default 90)
   deploymentArchiveRetentionDays?: string;
 
+  // Long-term backup target. Type 's3' | 'nfs' | 'smb'; config is a JSON
+  // object string with the matching connection fields (s3: endpoint,
+  // accessKey, secretKey, bucket, port?, useSsl?, region?; nfs: path
+  // mounted into the cloudly container; smb: host, share, username?,
+  // password?, domain?, port?). Absent = no offload, backups stay on the
+  // cache tier.
+  backupExternalTargetType?: string;
+  backupExternalTargetConfig?: string;
+
+  // Node-local archive cache retention in days (corestore prune; default 30)
+  backupNodeCacheKeepDays?: string;
+
   // BaseOS enrollment
   baseosJoinToken?: string;
 

package/ts/requests/backup.ts

@@ -1,5 +1,7 @@
 import * as plugins from '../plugins.js';
 import type {
+  IArchivePruneResult,
+  IArchiveRetentionPolicy,
   IBackupArchiveManifest,
   IBackupArchiveObject,
   IBackupRecord,
@@ -196,3 +198,19 @@ extends plugins.typedrequestInterfaces.implementsTR<
     contentsBase64: string;
   };
 }
+
+export interface IReq_Cloudly_Coreflow_PruneNodeArchive
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Coreflow_PruneNodeArchive
+> {
+  method: 'coreflowPruneNodeArchive';
+  request: {
+    retention: IArchiveRetentionPolicy;
+    dryRun?: boolean;
+  };
+  response: {
+    found: boolean;
+    result?: IArchivePruneResult;
+  };
+}