@phpsandbox/sdk 0.2.2 → 0.3.0

package/dist/integrations/account.d.ts

@@ -19,6 +19,7 @@ export interface IntegrationData {
     provider: IntegrationProvider;
     label: string | null;
     createdAt: string | null;
+    unlinkedAt?: string | null;
 }
 export type IntegrationReference = string | Integration;
 export declare class IntegrationApi {

package/dist/publication/instance.d.ts

@@ -21,7 +21,6 @@ export declare class PublicationInstance<TProvider extends PublicationProviderNa
     refresh(): Promise<PublicationInstance<TProvider>>;
     /** Start or reattach to the current release stream without queuing another release. */
     follow(): PublicationRun<TProvider>;
-    publish(): Promise<PublicationRun<TProvider>>;
     destroy(options?: PublicationDestroyOptions): Promise<void>;
     wait(options?: {
         intervalMs?: number;

package/dist/publication/instance.js

@@ -36,15 +36,6 @@ export class PublicationInstance {
     follow() {
         return new PublicationRun(this, this.client).start();
     }
-    async publish() {
-        if (!this.notebookId) {
-            throw new PHPSandboxError('Publishing requires a notebook-scoped publication instance.');
-        }
-        const response = await this.client.post(`/notebook/${encodeURIComponent(this.notebookId)}/publication`);
-        const run = new PublicationRun(new PublicationInstance(response.data, this.client, this.notebookId), this.client);
-        run.start();
-        return run;
-    }
     async destroy(options = {}) {
         const query = options.deleteResources ? '?deleteResources=1' : '';
         await this.client.delete(`/publications/${encodeURIComponent(this.data.id)}${query}`);

package/dist/publication/notebook.d.ts

@@ -1,8 +1,7 @@
 import type { Client } from '../index.js';
 import { PublicationInstance } from './instance.js';
-import { PublicationRun } from './run.js';
 import { PublicationResources } from './resources.js';
-import type { PlannedPublishInput, PublicationApplicationPlan, PublicationApplicationPlanInput, PublicationApplicationPublishInput, PublicationApplicationData, PublicationPlan, PublicationPlanInput, PublicationProviderName, PublicationReadiness, PublicationResourceCatalog } from './types.js';
+import type { PublicationProjectConfiguration, PublicationConfigurationUpdate, PublicationApplicationPlan, PublicationApplicationPlanInput, PublicationApplicationPublishInput, PublicationApplicationPublishResult, PublicationApplicationData, PublicationReadiness, PublicationResourceCatalog } from './types.js';
 export declare class NotebookPublication {
     private readonly notebookId;
     private readonly client;
@@ -11,14 +10,16 @@ export declare class NotebookPublication {
     private get path();
     current(): Promise<PublicationInstance | null>;
     readiness(): Promise<PublicationReadiness>;
-    /** Review a publishing plan without committing changes or creating resources. */
-    prepare<TName extends PublicationProviderName>(input: PublicationPlanInput<TName>): Promise<PublicationPlan<TName>>;
-    /** Review a multi-component publishing plan without creating resources or starting releases. */
-    prepareApplication(input: PublicationApplicationPlanInput): Promise<PublicationApplicationPlan>;
-    /** Publish every component in a reviewed application plan. */
-    publishApplication(input: PublicationApplicationPublishInput): Promise<PublicationApplicationData>;
+    /** Inspect saved configuration and the actual inventory, including removed and legacy apps. */
+    configuration(): Promise<PublicationProjectConfiguration>;
+    /** Explicit operations preserve omitted apps. Removals never stop deployments or delete resource data. */
+    updateConfiguration(input: PublicationConfigurationUpdate): Promise<PublicationProjectConfiguration>;
+    /** Review all or selected configured apps at an exact saved revision. */
+    prepare(input: PublicationApplicationPlanInput): Promise<PublicationApplicationPlan>;
+    /** Publish the exact app selection in a server-owned review. */
+    publish(input: PublicationApplicationPublishInput): Promise<PublicationApplicationPublishResult>;
     application(applicationId: string): Promise<PublicationApplicationData>;
-    /** Retry only failed components while leaving healthy components untouched. */
+    /** Retry failed apps and pending route attachments while preserving running releases. */
     retryApplication(applicationId: string): Promise<PublicationApplicationData>;
     destroyApplication(applicationId: string, options?: {
         deleteResources?: boolean;
@@ -26,6 +27,4 @@ export declare class NotebookPublication {
     private startApplicationRuns;
     catalog(provider: 'laravel-cloud' | 'cloudflare-containers'): Promise<PublicationResourceCatalog>;
     catalog(provider: 'ssh-server', serverId: string): Promise<PublicationResourceCatalog>;
-    /** Core validates the plan, prepares source and executes publishing. */
-    publish(input?: PlannedPublishInput): Promise<PublicationRun>;
 }

package/dist/publication/notebook.js

@@ -26,24 +26,29 @@ export class NotebookPublication {
     async readiness() {
         return (await this.client.get(`${this.path}/publication/readiness`)).data;
     }
-    /** Review a publishing plan without committing changes or creating resources. */
+    /** Inspect saved configuration and the actual inventory, including removed and legacy apps. */
+    async configuration() {
+        return (await this.client.get(`${this.path}/publication/configuration`)).data;
+    }
+    /** Explicit operations preserve omitted apps. Removals never stop deployments or delete resource data. */
+    async updateConfiguration(input) {
+        return (await this.client.patch(`${this.path}/publication/configuration`, input)).data;
+    }
+    /** Review all or selected configured apps at an exact saved revision. */
     async prepare(input) {
         return (await this.client.post(`${this.path}/publication/plan`, input)).data;
     }
-    /** Review a multi-component publishing plan without creating resources or starting releases. */
-    async prepareApplication(input) {
-        return (await this.client.post(`${this.path}/publication/application-plan`, input)).data;
-    }
-    /** Publish every component in a reviewed application plan. */
-    async publishApplication(input) {
-        const application = (await this.client.post(`${this.path}/publication/application`, input)).data;
-        this.startApplicationRuns(application);
+    /** Publish the exact app selection in a server-owned review. */
+    async publish(input) {
+        const application = (await this.client.post(`${this.path}/publication`, input)).data;
+        if (!('confirmationRequired' in application))
+            this.startApplicationRuns(application);
         return application;
     }
     async application(applicationId) {
         return (await this.client.get(`${this.path}/publication/application/${encodeURIComponent(applicationId)}`)).data;
     }
-    /** Retry only failed components while leaving healthy components untouched. */
+    /** Retry failed apps and pending route attachments while preserving running releases. */
     async retryApplication(applicationId) {
         const application = (await this.client.post(`${this.path}/publication/application/${encodeURIComponent(applicationId)}/retry`, {})).data;
         this.startApplicationRuns(application);
@@ -54,10 +59,12 @@ export class NotebookPublication {
         await this.client.delete(`${this.path}/publication/application/${encodeURIComponent(applicationId)}${query}`);
     }
     startApplicationRuns(application) {
-        for (const component of application.components) {
-            if (!['pending', 'queued', 'building', 'deploying'].includes(component.publication.status))
+        for (const app of application.apps) {
+            if (!(application.selectedAppIds ?? []).includes(app.appId))
+                continue;
+            if (!['pending', 'queued', 'building', 'deploying'].includes(app.publication.status))
                 continue;
-            new PublicationRun(new PublicationInstance(component.publication, this.client, this.notebookId), this.client).start();
+            new PublicationRun(new PublicationInstance(app.publication, this.client, this.notebookId), this.client).start();
         }
     }
     async catalog(provider, serverId) {
@@ -68,9 +75,4 @@ export class NotebookPublication {
         return (await this.client.get(`${this.path}/publication/catalog?${query}`))
             .data;
     }
-    /** Core validates the plan, prepares source and executes publishing. */
-    async publish(input) {
-        const response = await this.client.post(`${this.path}/publication`, input);
-        return new PublicationRun(new PublicationInstance(response.data, this.client, this.notebookId), this.client).start();
-    }
 }

package/dist/publication/types.d.ts

@@ -52,6 +52,13 @@ export interface PublicationReadiness {
     productionVariables: string[];
     missingVariables: string[];
     warnings: string[];
+    configuration?: PublicationConfigurationField[];
+    defaultBuild?: 'laravel' | 'dockerfile' | 'unresolved' | null;
+}
+export interface PublicationConfigurationField {
+    name: string;
+    requirement: 'required' | 'optional' | 'platform';
+    source: string;
 }
 export type PublicationResourceMode = 'none' | 'create' | 'reuse' | 'external' | 'enable';
 export interface PublicationResourceSelection {
@@ -62,18 +69,6 @@ export interface PublicationResourceSelection {
     size?: string;
     config?: Record<string, string | number | boolean | null>;
 }
-export type PublicationPlanProviderInput<TName extends PublicationProviderName = PublicationProviderName> = {
-    [Name in TName]: {
-        name: Name;
-    } & Partial<PublicationProviderInputs[Name]>;
-}[TName];
-export interface PublicationPlanInput<TName extends PublicationProviderName = PublicationProviderName> {
-    slug?: string;
-    provider: PublicationPlanProviderInput<TName>;
-    requirements?: PublicationRequirement[];
-    resources?: Partial<Record<PublicationResourceKind, PublicationResourceSelection>>;
-}
-export type PlannedPublishInput = PublishInput & Pick<PublicationPlanInput, 'requirements' | 'resources'>;
 export interface PublicationAccessCapabilities {
     routing: 'platform' | 'provider';
     protection: boolean;
@@ -82,8 +77,8 @@ export interface PublicationAccessCapabilities {
 export interface PublicationCapabilities {
     source: 'git' | 'workspace';
     sourceProviders?: string[];
-    buildModes?: Array<PublicationComponentBuild['mode']>;
-    componentKinds?: PublicationComponentKind[];
+    buildModes?: Array<PublicationAppBuild['mode']>;
+    appKinds?: Array<'http'>;
     resourceCleanup?: boolean;
     resources: Record<PublicationResourceKind, PublicationResourceMode[]>;
     access: {
@@ -116,6 +111,10 @@ export interface PublicationCatalogResourceType {
     configFields: PublicationCatalogConfigField[];
 }
 export interface PublicationResourceCatalog {
+    accounts?: {
+        id: string;
+        name: string;
+    }[];
     provider: PublicationProviderName;
     scope: string | null;
     capabilities: PublicationCapabilities;
@@ -136,56 +135,14 @@ export interface PublicationResourceCatalog {
     }[];
     pricingUrl: string | null;
 }
-export interface PublicationPlan<TName extends PublicationProviderName = PublicationProviderName> {
-    provider: TName;
-    capabilities: PublicationCapabilities;
-    readiness: PublicationReadiness;
-    source: {
-        type: 'git' | 'workspace';
-        repository: string | null;
-        branch: string | null;
-        commitAndPush: boolean;
-        providerAccess: 'verified' | 'confirmed' | 'confirmation_required' | 'not_required';
-    };
-    resources: Array<{
-        kind: PublicationResourceKind;
-        mode: PublicationResourceMode | 'unconfigured';
-        engine: string | null;
-        required: boolean;
-        recommended: boolean;
-        supported: boolean;
-        selection: PublicationResourceSelection | boolean | null;
-    }>;
-    blockers: Array<{
-        code: string;
-        message: string;
-    }>;
-    ready: boolean;
-    input: PublicationPlanInput<TName>;
-    cost: {
-        status: 'unknown';
-        message: string;
-    };
-}
-export type PublicationComponentKind = 'frontend' | 'http-service' | 'static-site' | 'worker' | 'scheduler';
 export type PublicationDockerfile = {
     source: 'generated';
     content: string;
-    digest?: string;
 } | {
     source: 'project';
     path: string;
-    digest?: string;
 };
-export type PublicationComponentBuild = {
-    mode: 'provider-native';
-    workingDirectory?: string;
-    context?: string;
-    installCommand?: string;
-    buildCommand?: string;
-    deployCommand?: string;
-    outputDirectory?: string;
-} | {
+export type PublicationContainerBuild = {
     mode: 'dockerfile';
     workingDirectory?: string;
     context?: string;
@@ -193,59 +150,174 @@ export type PublicationComponentBuild = {
     target?: string;
     arguments?: Record<string, string>;
     secrets?: string[];
+};
+export type PublicationNativeBuild = {
+    mode: 'provider-native';
+    installCommand?: string;
+    buildCommand?: string;
+    deployCommand?: string;
+};
+export type PublicationAppBuild = PublicationContainerBuild | PublicationNativeBuild;
+export type PublicationRoutingDraft = {
+    mode: 'managed';
+    routes?: never;
 } | {
-    mode: 'image';
-    reference: string;
+    mode: 'custom';
+    routes: [{
+        hostname: string;
+    }, ...Array<{
+        hostname: string;
+    }>];
 };
-export interface PublicationComponentRuntime {
-    kind?: 'http' | 'static' | 'process';
-    command?: string[];
-    port?: number;
-    healthCheck?: {
+export interface PublicationManagedAddress {
+    slug: string;
+    url: string;
+}
+export type PublicationRouting = PublicationRoutingDraft & {
+    managedAddress: PublicationManagedAddress;
+};
+export type PublicationContainerRuntime = {
+    mode: 'container';
+    port: number;
+    healthCheck: {
         path: string;
     };
-}
-export type PublicationComponentPlacement<TName extends PublicationProviderName = PublicationProviderName> = {
-    [Name in TName]: {
-        provider: Name;
-    } & Partial<PublicationProviderInputs[Name]>;
-}[TName];
-export interface PublicationApplicationComponentInput<TName extends PublicationProviderName = PublicationProviderName> {
-    id: string;
-    kind: PublicationComponentKind;
+    command?: string[];
+};
+export type PublicationNativeRuntime = {
+    mode: 'provider-native';
+    port?: never;
+    command?: never;
+    healthCheck?: never;
+};
+interface PublicationAppDraftBase {
+    name: string;
+    kind: 'http';
     root: string;
-    build: PublicationComponentBuild;
-    sourceDependencies?: string[];
-    runtime?: PublicationComponentRuntime;
-    resources?: string[];
-    placement: PublicationComponentPlacement<TName>;
-}
-export interface PublicationApplicationResourceInput {
+    slug?: string;
+    routing: PublicationRoutingDraft;
+    resourceIds?: string[];
+}
+/** Only executable HTTP workloads are accepted. Runtime and build follow the destination. */
+export type PublicationAppDraft = PublicationAppDraftBase & ({
+    destination: {
+        provider: 'ssh-server';
+        serverId?: string;
+    };
+    build: PublicationContainerBuild;
+    runtime: PublicationContainerRuntime;
+} | {
+    destination: {
+        provider: 'cloudflare-containers';
+    } & Partial<Omit<CloudflareContainersProviderOptions, 'resources'>>;
+    build: Omit<PublicationContainerBuild, 'target' | 'arguments' | 'secrets'>;
+    runtime: PublicationContainerRuntime;
+} | {
+    destination: {
+        provider: 'laravel-cloud';
+        region?: LaravelCloudProviderInput['region'];
+        setup?: Pick<NonNullable<LaravelCloudProviderInput['setup']>, 'repositoryAccessConfirmed' | 'workerPlacement' | 'workerSize'>;
+    };
+    build: PublicationNativeBuild;
+    runtime: PublicationNativeRuntime;
+});
+/** Server-issued ID and managed address remain stable through names and app-count changes. */
+export type PublicationApp = PublicationAppDraft extends infer Draft ? Draft extends PublicationAppDraft ? Omit<Draft, 'slug' | 'routing' | 'resourceIds'> & {
+    id: string;
+    routing: PublicationRouting;
+    resourceIds: string[];
+} : never : never;
+export type PublicationApplicationResourceInput = {
     id: string;
     kind: PublicationResourceKind;
-    mode: PublicationResourceMode;
     engine?: string;
     provider?: PublicationProviderName;
-    selection?: Omit<PublicationResourceSelection, 'mode'>;
+} & ({
+    mode: 'none' | 'external' | 'enable';
+    selection?: never;
+} | {
+    mode: 'reuse';
+    selection: {
+        id: string;
+    };
+} | {
+    mode: 'create';
+    provider: 'laravel-cloud';
+    kind: 'storage';
+    selection?: never;
+} | {
+    mode: 'create';
+    selection: {
+        type: string;
+        version?: string;
+        size?: string;
+        config?: Record<string, string | number | boolean | null>;
+    };
+});
+export type PublicationConfigurationOperation = {
+    op: 'add-app';
+    app: PublicationAppDraft;
+    adoptPublicationId?: string;
+} | {
+    op: 'update-app';
+    appId: string;
+    app: PublicationAppDraft;
+} | {
+    op: 'remove-app';
+    appId: string;
+} | {
+    op: 'add-resource';
+    resource: PublicationApplicationResourceInput;
+} | {
+    op: 'update-resource';
+    resourceId: string;
+    resource: PublicationApplicationResourceInput;
+} | {
+    op: 'remove-resource';
+    resourceId: string;
+};
+export interface PublicationConfigurationUpdate {
+    expectedRevision: number;
+    operations: PublicationConfigurationOperation[];
 }
-export interface PublicationApplicationRouteInput {
-    hostname: string;
-    component: string;
+export interface PublicationProjectConfiguration {
+    schemaVersion: 1;
+    proposal: {
+        id: string;
+        token: string;
+    } | null;
+    id: string | null;
+    revision: number;
+    apps: PublicationApp[];
+    resources: PublicationApplicationResourceInput[];
+    deployments: Array<{
+        appId: string | null;
+        configured: boolean;
+        publication: PublicationData;
+    }>;
 }
 export interface PublicationApplicationPlanInput {
-    schemaVersion: 1;
-    slug?: string;
-    source?: {
-        repository?: string;
-        revision?: string;
-        root?: string;
-    };
-    components: PublicationApplicationComponentInput[];
-    resources?: PublicationApplicationResourceInput[];
-    routes?: PublicationApplicationRouteInput[];
+    expectedRevision: number;
+    appIds?: string[];
 }
-/** A draft becomes executable only through its server-owned review reference. */
-export interface PublicationApplicationPlan extends PublicationApplicationPlanInput {
+export interface PublicationApplicationPlan {
+    schemaVersion: 1;
+    configurationId: string;
+    configurationRevision: number;
+    apps: Array<PublicationApp & {
+        action: 'create' | 'update' | 'retry';
+        publicationId: string | null;
+        routeAttachment: 'pending_after_deployment' | 'not_required';
+        /** Digest fingerprints the reviewed workspace; revision is the last synced Git commit, before native commit-and-push preparation. */
+        source: {
+            type: 'workspace' | 'git';
+            repository: string | null;
+            branch: string | null;
+            revision: string | null;
+            digest: string | null;
+        };
+    }>;
+    resources: PublicationApplicationResourceInput[];
     review: {
         id: string;
         ready: boolean;
@@ -253,34 +325,56 @@ export interface PublicationApplicationPlan extends PublicationApplicationPlanIn
             code: string;
             message: string;
         }>;
-        action: 'create' | 'update' | 'retry';
-        publicationId: string | null;
         destinations: Record<string, string | null>;
         productionVariables: string[];
-        configuration: Array<{
-            name: string;
-            requirement: 'required' | 'optional' | 'platform';
-            source: string;
-        }>;
+        configuration: PublicationConfigurationField[];
         source: {
-            type: 'workspace' | 'git';
+            type: 'workspace' | 'git' | 'mixed';
             repository: string | null;
             branch: string | null;
+            revision: string | null;
+            digest: string | null;
         };
         digest: string;
+        proposal: string;
     };
 }
 export interface PublicationApplicationPublishInput {
     reviewId: string;
-}
-export interface PublicationApplicationComponentData {
-    componentId: string;
+    proposal: string;
+    appIds?: string[];
+}
+export interface PublicationApplicationConfirmationRequired {
+    confirmationRequired: true;
+    plan: PublicationApplicationPlan;
+    changes: string[];
+}
+export type PublicationApplicationPublishResult = PublicationApplicationData | PublicationApplicationConfirmationRequired;
+export interface PublicationApplicationAppData {
+    appId: string;
+    configurationRevision: number | null;
     publication: PublicationData;
+    runtime: {
+        status: 'healthy' | 'unknown' | 'stopped';
+        state: Record<string, unknown>;
+    };
+    routing: {
+        managedAddress: PublicationManagedAddress;
+        status: 'connected' | 'pending' | 'failed';
+        routes: Array<{
+            hostname: string;
+            status: string;
+            error: string | null;
+        }>;
+        errors: Record<string, string>;
+    };
 }
 export interface PublicationApplicationData {
     id: string;
-    status: 'publishing' | 'healthy' | 'failed' | 'deleted';
-    components: PublicationApplicationComponentData[];
+    status: 'publishing' | 'healthy' | 'partial' | 'failed' | 'deleted';
+    apps: PublicationApplicationAppData[];
+    reviewId?: string;
+    selectedAppIds?: string[];
 }
 export interface PublicationDnsInstructions {
     stage: 'ownership' | 'traffic' | 'connected';
@@ -308,14 +402,12 @@ export type PublicationProvider<TName extends PublicationProviderName = Publicat
         name: Name;
     } & PublicationProviderData[Name];
 }[TName];
-export interface PublishInput<TName extends PublicationProviderName = PublicationProviderName> {
-    slug: string;
-    provider: PublicationProviderInput<TName>;
-    protection?: PublicationProtectionInput;
-    metadata?: Record<string, unknown>;
-}
 export interface PublicationBuildData<TProvider extends PublicationProviderName = PublicationProviderName> {
     id: string;
+    appId?: string | null;
+    configurationRevision?: number | null;
+    reviewId?: string | null;
+    sourceRevision?: string | null;
     status: PublicationBuildStatus;
     strategy: string;
     provider: PublicationProvider<TProvider>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "The TypeScript SDK for PHPSandbox cloud development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",