@serve.zone/interfaces 6.0.0 → 6.1.0

package/changelog.md

@@ -3,6 +3,25 @@
 ## Pending
 
 
+## 2026-05-26 - 6.1.0
+
+- add generic hosted app lifecycle contracts (hostedapp)
+  - Adds service-scoped runtime identity, lifecycle reporting, bootstrap action, and managed upgrade request interfaces.
+  - Adds optional hosted app lifecycle state to service data for host runtimes such as Onebox and Cloudly.
+
+### Features
+
+- add hosted app lifecycle contracts (hostedapp)
+  - Add hosted app runtime identity, lifecycle state, bootstrap action, and managed upgrade data contracts
+  - Expose typed request interfaces for lifecycle reporting, bootstrap actions, and managed upgrade operations
+  - Allow services to include optional hosted app lifecycle state
+
+## 2026-05-26 - 6.0.1
+
+- add App Store service upgrade contracts (appstore)
+  - Adds App Store upgrade preview, operation tracking, start/apply, and progress push request contracts
+  - Adds service-level App Store upgrade policy, published ports, and service IDs to related service types
+
 ## 2026-05-25 - 6.0.0
 
 ### Breaking Changes

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/appstore/types.d.ts

@@ -160,6 +160,7 @@ export interface IAppStoreInstallRequest {
     envVars?: Record<string, string>;
 }
 export interface IUpgradeableAppStoreService {
+    serviceId?: string;
     serviceName: string;
     appTemplateId: string;
     currentVersion: string;

package/dist_ts/data/hostedapp.d.ts

@@ -0,0 +1,57 @@
+export type THostedAppHostType = 'onebox' | 'cloudly' | string;
+export type THostedAppRuntimeStatus = 'starting' | 'running' | 'setupRequired' | 'degraded' | 'stopped' | 'unknown';
+export type THostedAppBootstrapActionType = 'setupLink' | 'credentials' | 'message';
+export type THostedAppBootstrapActionStatus = 'requested' | 'ready' | 'completed' | 'dismissed' | 'expired';
+export type THostedAppUpgradeStatus = 'unknown' | 'upToDate' | 'available' | 'running' | 'success' | 'failed';
+export interface IHostedAppRuntimeIdentity {
+    appInstanceId: string;
+    appControlToken: string;
+    hostType?: THostedAppHostType;
+}
+export interface IHostedAppBootstrapAction {
+    id: string;
+    type: THostedAppBootstrapActionType;
+    status: THostedAppBootstrapActionStatus;
+    label: string;
+    url?: string;
+    username?: string;
+    password?: string;
+    message?: string;
+    expiresAt?: number;
+    createdAt: number;
+    updatedAt: number;
+    completedAt?: number;
+    dismissedAt?: number;
+}
+export interface IHostedAppUpgradeState {
+    status: THostedAppUpgradeStatus;
+    appTemplateId?: string;
+    currentVersion?: string;
+    latestVersion?: string;
+    targetVersion?: string;
+    operationId?: string;
+    warnings?: string[];
+    blockers?: string[];
+    error?: string;
+    startedAt?: number;
+    updatedAt?: number;
+    completedAt?: number;
+}
+export interface IHostedAppLifecycleReport {
+    appName?: string;
+    appVersion?: string;
+    publicUrl?: string;
+    runtimeStatus?: THostedAppRuntimeStatus;
+    statusMessage?: string;
+    capabilities?: string[];
+}
+export interface IHostedAppLifecycleState extends IHostedAppLifecycleReport {
+    appInstanceId: string;
+    hostType: THostedAppHostType;
+    reportedAt?: number;
+    bootstrapAction?: IHostedAppBootstrapAction;
+    upgradeState?: IHostedAppUpgradeState;
+}
+export type IHostedAppBootstrapActionRequest = Omit<IHostedAppBootstrapAction, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'completedAt' | 'dismissedAt'> & {
+    id?: string;
+};

package/dist_ts/data/hostedapp.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaG9zdGVkYXBwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9ob3N0ZWRhcHAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist_ts/data/index.d.ts

@@ -7,6 +7,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './hostedapp.js';
 export * from './image.js';
 export * from './registry.js';
 export * from './secretbundle.js';

package/dist_ts/data/index.js

@@ -7,6 +7,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './hostedapp.js';
 export * from './image.js';
 export * from './registry.js';
 export * from './secretbundle.js';
@@ -22,4 +23,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/data/service.d.ts

@@ -1,5 +1,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';
 export interface IServiceVolume {
     /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
     name?: string;
@@ -26,6 +28,8 @@ export interface IService {
         deployOnPush?: boolean;
         appTemplateId?: string;
         appTemplateVersion?: string;
+        appStoreUpgradePolicy?: 'manual' | 'notify' | 'auto';
+        hostedAppLifecycle?: IHostedAppLifecycleState;
         environment: {
             [key: string]: string;
         };
@@ -71,6 +75,7 @@ export interface IService {
             };
         };
         volumes?: IServiceVolume[];
+        publishedPorts?: IAppStorePublishedPort[];
         resources?: IServiceRessources;
         domains: {
             /**

package/dist_ts/requests/appstore.d.ts

@@ -2,6 +2,45 @@ import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
 import type { IService } from '../data/service.js';
 import type { IAppStoreApp, IAppStoreAppMeta, IAppStoreInstallRequest, IAppStoreVersionConfig, IUpgradeableAppStoreService } from '../appstore/index.js';
+export type TAppStoreUpgradeStatus = 'running' | 'success' | 'failed';
+export type TAppStoreUpgradeStep = 'queued' | 'validating' | 'migration' | 'applying' | 'updating-service' | 'pushing-config' | 'complete' | 'failed';
+export interface IAppStoreUpgradeChange {
+    field: string;
+    currentValue: string;
+    targetValue: string;
+}
+export interface IAppStoreUpgradePreview {
+    serviceId: string;
+    serviceName: string;
+    appTemplateId: string;
+    fromVersion: string;
+    targetVersion: string;
+    resolvedTargetVersion: string;
+    hasMigration: boolean;
+    requiresManualReview: boolean;
+    changes: IAppStoreUpgradeChange[];
+    warnings: string[];
+    blockers: string[];
+    config: IAppStoreVersionConfig;
+    appMeta: IAppStoreAppMeta;
+}
+export interface IAppStoreUpgradeOperation {
+    id: string;
+    serviceId: string;
+    serviceName: string;
+    appTemplateId: string;
+    fromVersion: string;
+    targetVersion: string;
+    status: TAppStoreUpgradeStatus;
+    step: TAppStoreUpgradeStep;
+    progressLines: string[];
+    warnings: string[];
+    error?: string;
+    startedAt: number;
+    updatedAt: number;
+    completedAt?: number;
+    service?: IService;
+}
 export interface IReq_Any_GetAppStoreTemplates extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_GetAppStoreTemplates> {
     method: 'getAppStoreTemplates';
     request: {
@@ -42,3 +81,53 @@ export interface IReq_Any_GetUpgradeableAppStoreServices extends plugins.typedre
         services: IUpgradeableAppStoreService[];
     };
 }
+export interface IReq_Any_GetAppStoreUpgradePreview extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_GetAppStoreUpgradePreview> {
+    method: 'getAppStoreUpgradePreview';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        targetVersion?: string;
+    };
+    response: {
+        preview: IAppStoreUpgradePreview;
+    };
+}
+export interface IReq_Any_UpgradeAppStoreService extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_UpgradeAppStoreService> {
+    method: 'upgradeAppStoreService';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        targetVersion: string;
+    };
+    response: {
+        service: IService;
+        warnings: string[];
+    };
+}
+export interface IReq_Any_StartAppStoreServiceUpgrade extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_StartAppStoreServiceUpgrade> {
+    method: 'startAppStoreServiceUpgrade';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        targetVersion: string;
+    };
+    response: {
+        operation: IAppStoreUpgradeOperation;
+    };
+}
+export interface IReq_Any_GetAppStoreUpgradeOperations extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_GetAppStoreUpgradeOperations> {
+    method: 'getAppStoreUpgradeOperations';
+    request: {
+        identity: IIdentity;
+    };
+    response: {
+        operations: IAppStoreUpgradeOperation[];
+    };
+}
+export interface IReq_Any_PushAppStoreUpgradeProgress extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_PushAppStoreUpgradeProgress> {
+    method: 'pushAppStoreUpgradeProgress';
+    request: {
+        operation: IAppStoreUpgradeOperation;
+    };
+    response: Record<string, never>;
+}

package/dist_ts/requests/hostedapp.d.ts

@@ -0,0 +1,63 @@
+import * as plugins from '../plugins.js';
+import type { IHostedAppBootstrapAction, IHostedAppBootstrapActionRequest, IHostedAppLifecycleReport, IHostedAppLifecycleState, IHostedAppRuntimeIdentity, IHostedAppUpgradeState } from '../data/hostedapp.js';
+export interface IReq_HostedApp_ReportLifecycleState extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HostedApp_ReportLifecycleState> {
+    method: 'hostedAppReportLifecycleState';
+    request: {
+        identity: IHostedAppRuntimeIdentity;
+        report: IHostedAppLifecycleReport;
+    };
+    response: {
+        state: IHostedAppLifecycleState;
+    };
+}
+export interface IReq_HostedApp_GetLifecycleState extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HostedApp_GetLifecycleState> {
+    method: 'hostedAppGetLifecycleState';
+    request: {
+        identity: IHostedAppRuntimeIdentity;
+    };
+    response: {
+        state: IHostedAppLifecycleState;
+    };
+}
+export interface IReq_HostedApp_RequestBootstrapAction extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HostedApp_RequestBootstrapAction> {
+    method: 'hostedAppRequestBootstrapAction';
+    request: {
+        identity: IHostedAppRuntimeIdentity;
+        action: IHostedAppBootstrapActionRequest;
+    };
+    response: {
+        action: IHostedAppBootstrapAction;
+        state: IHostedAppLifecycleState;
+    };
+}
+export interface IReq_HostedApp_CompleteBootstrapAction extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HostedApp_CompleteBootstrapAction> {
+    method: 'hostedAppCompleteBootstrapAction';
+    request: {
+        identity: IHostedAppRuntimeIdentity;
+        actionId?: string;
+        message?: string;
+    };
+    response: {
+        state: IHostedAppLifecycleState;
+    };
+}
+export interface IReq_HostedApp_StartManagedUpgrade extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HostedApp_StartManagedUpgrade> {
+    method: 'hostedAppStartManagedUpgrade';
+    request: {
+        identity: IHostedAppRuntimeIdentity;
+        targetVersion?: string;
+    };
+    response: {
+        upgradeState: IHostedAppUpgradeState;
+        state: IHostedAppLifecycleState;
+    };
+}
+export interface IReq_HostedApp_GetManagedUpgradeStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HostedApp_GetManagedUpgradeStatus> {
+    method: 'hostedAppGetManagedUpgradeStatus';
+    request: {
+        identity: IHostedAppRuntimeIdentity;
+    };
+    response: {
+        upgradeState: IHostedAppUpgradeState;
+    };
+}

package/dist_ts/requests/hostedapp.js

@@ -0,0 +1,2 @@
+import * as plugins from '../plugins.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaG9zdGVkYXBwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvcmVxdWVzdHMvaG9zdGVkYXBwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDIn0=

package/dist_ts/requests/index.d.ts

@@ -10,6 +10,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
@@ -26,5 +27,6 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
+export * from './hostedapp.js';

package/dist_ts/requests/index.js

@@ -11,6 +11,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
@@ -27,6 +28,7 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGtCQUFrQixNQUFNLGlCQUFpQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyx3QkFBd0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxhQUFhLE1BQU0sWUFBWSxDQUFDO0FBQzVDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLG9CQUFvQixNQUFNLG1CQUFtQixDQUFDO0FBQzFELE9BQU8sS0FBSyxtQkFBbUIsTUFBTSxrQkFBa0IsQ0FBQztBQUN4RCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBRWhELE9BQU8sRUFDTCxhQUFhLElBQUksS0FBSyxFQUN0QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsbUJBQW1CLElBQUksV0FBVyxFQUNsQyxlQUFlLElBQUksT0FBTyxFQUMxQixjQUFjLElBQUksTUFBTSxFQUN4QixrQkFBa0IsSUFBSSxVQUFVLEVBQ2hDLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLHdCQUF3QixJQUFJLGdCQUFnQixFQUM1QyxnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDIn0=
+export * from './hostedapp.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGtCQUFrQixNQUFNLGlCQUFpQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyx3QkFBd0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssaUJBQWlCLE1BQU0sZ0JBQWdCLENBQUM7QUFDcEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxvQkFBb0IsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQ0wsYUFBYSxJQUFJLEtBQUssRUFDdEIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLG1CQUFtQixJQUFJLFdBQVcsRUFDbEMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsa0JBQWtCLElBQUksVUFBVSxFQUNoQyxXQUFXLElBQUksR0FBRyxFQUNsQixjQUFjLElBQUksTUFBTSxFQUN4Qix3QkFBd0IsSUFBSSxnQkFBZ0IsRUFDNUMsaUJBQWlCLElBQUksU0FBUyxFQUM5QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUMifQ==

package/package.json

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

package/ts/appstore/types.ts

@@ -181,6 +181,7 @@ export interface IAppStoreInstallRequest {
 }
 
 export interface IUpgradeableAppStoreService {
+  serviceId?: string;
   serviceName: string;
   appTemplateId: string;
   currentVersion: string;

package/ts/data/hostedapp.ts

@@ -0,0 +1,87 @@
+export type THostedAppHostType = 'onebox' | 'cloudly' | string;
+
+export type THostedAppRuntimeStatus =
+  | 'starting'
+  | 'running'
+  | 'setupRequired'
+  | 'degraded'
+  | 'stopped'
+  | 'unknown';
+
+export type THostedAppBootstrapActionType = 'setupLink' | 'credentials' | 'message';
+
+export type THostedAppBootstrapActionStatus =
+  | 'requested'
+  | 'ready'
+  | 'completed'
+  | 'dismissed'
+  | 'expired';
+
+export type THostedAppUpgradeStatus =
+  | 'unknown'
+  | 'upToDate'
+  | 'available'
+  | 'running'
+  | 'success'
+  | 'failed';
+
+export interface IHostedAppRuntimeIdentity {
+  appInstanceId: string;
+  appControlToken: string;
+  hostType?: THostedAppHostType;
+}
+
+export interface IHostedAppBootstrapAction {
+  id: string;
+  type: THostedAppBootstrapActionType;
+  status: THostedAppBootstrapActionStatus;
+  label: string;
+  url?: string;
+  username?: string;
+  password?: string;
+  message?: string;
+  expiresAt?: number;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  dismissedAt?: number;
+}
+
+export interface IHostedAppUpgradeState {
+  status: THostedAppUpgradeStatus;
+  appTemplateId?: string;
+  currentVersion?: string;
+  latestVersion?: string;
+  targetVersion?: string;
+  operationId?: string;
+  warnings?: string[];
+  blockers?: string[];
+  error?: string;
+  startedAt?: number;
+  updatedAt?: number;
+  completedAt?: number;
+}
+
+export interface IHostedAppLifecycleReport {
+  appName?: string;
+  appVersion?: string;
+  publicUrl?: string;
+  runtimeStatus?: THostedAppRuntimeStatus;
+  statusMessage?: string;
+  capabilities?: string[];
+}
+
+export interface IHostedAppLifecycleState extends IHostedAppLifecycleReport {
+  appInstanceId: string;
+  hostType: THostedAppHostType;
+  reportedAt?: number;
+  bootstrapAction?: IHostedAppBootstrapAction;
+  upgradeState?: IHostedAppUpgradeState;
+}
+
+export type IHostedAppBootstrapActionRequest = Omit<
+  IHostedAppBootstrapAction,
+  'id' | 'status' | 'createdAt' | 'updatedAt' | 'completedAt' | 'dismissedAt'
+> & {
+  id?: string;
+};

package/ts/data/index.ts

@@ -7,6 +7,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './hostedapp.js';
 export * from './image.js';
 export * from './registry.js';
 export * from './secretbundle.js';

package/ts/data/service.ts

@@ -1,5 +1,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';
 
 export interface IServiceVolume {
   /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -28,6 +30,8 @@ export interface IService {
     deployOnPush?: boolean;
     appTemplateId?: string;
     appTemplateVersion?: string;
+    appStoreUpgradePolicy?: 'manual' | 'notify' | 'auto';
+    hostedAppLifecycle?: IHostedAppLifecycleState;
     environment: { [key: string]: string };
     /**
      * the main secret bundle id, exclusive to the service
@@ -74,6 +78,7 @@ export interface IService {
       custom?: { [domain: string]: string };
     };
     volumes?: IServiceVolume[];
+    publishedPorts?: IAppStorePublishedPort[];
     resources?: IServiceRessources;
     domains: {
       /**

package/ts/requests/appstore.ts

@@ -9,6 +9,58 @@ import type {
   IUpgradeableAppStoreService,
 } from '../appstore/index.js';
 
+export type TAppStoreUpgradeStatus = 'running' | 'success' | 'failed';
+
+export type TAppStoreUpgradeStep =
+  | 'queued'
+  | 'validating'
+  | 'migration'
+  | 'applying'
+  | 'updating-service'
+  | 'pushing-config'
+  | 'complete'
+  | 'failed';
+
+export interface IAppStoreUpgradeChange {
+  field: string;
+  currentValue: string;
+  targetValue: string;
+}
+
+export interface IAppStoreUpgradePreview {
+  serviceId: string;
+  serviceName: string;
+  appTemplateId: string;
+  fromVersion: string;
+  targetVersion: string;
+  resolvedTargetVersion: string;
+  hasMigration: boolean;
+  requiresManualReview: boolean;
+  changes: IAppStoreUpgradeChange[];
+  warnings: string[];
+  blockers: string[];
+  config: IAppStoreVersionConfig;
+  appMeta: IAppStoreAppMeta;
+}
+
+export interface IAppStoreUpgradeOperation {
+  id: string;
+  serviceId: string;
+  serviceName: string;
+  appTemplateId: string;
+  fromVersion: string;
+  targetVersion: string;
+  status: TAppStoreUpgradeStatus;
+  step: TAppStoreUpgradeStep;
+  progressLines: string[];
+  warnings: string[];
+  error?: string;
+  startedAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  service?: IService;
+}
+
 export interface IReq_Any_GetAppStoreTemplates extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_GetAppStoreTemplates
@@ -64,3 +116,73 @@ export interface IReq_Any_GetUpgradeableAppStoreServices extends plugins.typedre
     services: IUpgradeableAppStoreService[];
   };
 }
+
+export interface IReq_Any_GetAppStoreUpgradePreview extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_GetAppStoreUpgradePreview
+> {
+  method: 'getAppStoreUpgradePreview';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    targetVersion?: string;
+  };
+  response: {
+    preview: IAppStoreUpgradePreview;
+  };
+}
+
+export interface IReq_Any_UpgradeAppStoreService extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_UpgradeAppStoreService
+> {
+  method: 'upgradeAppStoreService';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    targetVersion: string;
+  };
+  response: {
+    service: IService;
+    warnings: string[];
+  };
+}
+
+export interface IReq_Any_StartAppStoreServiceUpgrade extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_StartAppStoreServiceUpgrade
+> {
+  method: 'startAppStoreServiceUpgrade';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    targetVersion: string;
+  };
+  response: {
+    operation: IAppStoreUpgradeOperation;
+  };
+}
+
+export interface IReq_Any_GetAppStoreUpgradeOperations extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_GetAppStoreUpgradeOperations
+> {
+  method: 'getAppStoreUpgradeOperations';
+  request: {
+    identity: IIdentity;
+  };
+  response: {
+    operations: IAppStoreUpgradeOperation[];
+  };
+}
+
+export interface IReq_Any_PushAppStoreUpgradeProgress extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_PushAppStoreUpgradeProgress
+> {
+  method: 'pushAppStoreUpgradeProgress';
+  request: {
+    operation: IAppStoreUpgradeOperation;
+  };
+  response: Record<string, never>;
+}

package/ts/requests/hostedapp.ts

@@ -0,0 +1,94 @@
+import * as plugins from '../plugins.js';
+import type {
+  IHostedAppBootstrapAction,
+  IHostedAppBootstrapActionRequest,
+  IHostedAppLifecycleReport,
+  IHostedAppLifecycleState,
+  IHostedAppRuntimeIdentity,
+  IHostedAppUpgradeState,
+} from '../data/hostedapp.js';
+
+export interface IReq_HostedApp_ReportLifecycleState extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_HostedApp_ReportLifecycleState
+> {
+  method: 'hostedAppReportLifecycleState';
+  request: {
+    identity: IHostedAppRuntimeIdentity;
+    report: IHostedAppLifecycleReport;
+  };
+  response: {
+    state: IHostedAppLifecycleState;
+  };
+}
+
+export interface IReq_HostedApp_GetLifecycleState extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_HostedApp_GetLifecycleState
+> {
+  method: 'hostedAppGetLifecycleState';
+  request: {
+    identity: IHostedAppRuntimeIdentity;
+  };
+  response: {
+    state: IHostedAppLifecycleState;
+  };
+}
+
+export interface IReq_HostedApp_RequestBootstrapAction extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_HostedApp_RequestBootstrapAction
+> {
+  method: 'hostedAppRequestBootstrapAction';
+  request: {
+    identity: IHostedAppRuntimeIdentity;
+    action: IHostedAppBootstrapActionRequest;
+  };
+  response: {
+    action: IHostedAppBootstrapAction;
+    state: IHostedAppLifecycleState;
+  };
+}
+
+export interface IReq_HostedApp_CompleteBootstrapAction extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_HostedApp_CompleteBootstrapAction
+> {
+  method: 'hostedAppCompleteBootstrapAction';
+  request: {
+    identity: IHostedAppRuntimeIdentity;
+    actionId?: string;
+    message?: string;
+  };
+  response: {
+    state: IHostedAppLifecycleState;
+  };
+}
+
+export interface IReq_HostedApp_StartManagedUpgrade extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_HostedApp_StartManagedUpgrade
+> {
+  method: 'hostedAppStartManagedUpgrade';
+  request: {
+    identity: IHostedAppRuntimeIdentity;
+    targetVersion?: string;
+  };
+  response: {
+    upgradeState: IHostedAppUpgradeState;
+    state: IHostedAppLifecycleState;
+  };
+}
+
+export interface IReq_HostedApp_GetManagedUpgradeStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_HostedApp_GetManagedUpgradeStatus
+> {
+  method: 'hostedAppGetManagedUpgradeStatus';
+  request: {
+    identity: IHostedAppRuntimeIdentity;
+  };
+  response: {
+    upgradeState: IHostedAppUpgradeState;
+  };
+}

package/ts/requests/index.ts

@@ -12,6 +12,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
@@ -42,6 +43,7 @@ export {
   dnsRequests as dns,
   domainRequests as domain,
   externalRegistryRequests as externalRegistry,
+  hostedAppRequests as hostedapp,
   identityRequests as identity,
   imageRequests as image,
   informRequests as inform,
@@ -61,3 +63,4 @@ export {
 };
 
 export * from './inform.js';
+export * from './hostedapp.js';