@phpsandbox/sdk 0.2.3 → 0.3.1

package/README.md

@@ -81,7 +81,7 @@ console.log(persistentFork.data.policy);
 
 Notes:
 
-- Runtime actions wait for the sandbox to become ready before Okra handles them.
+- Runtime actions wait for the sandbox to become ready before the runtime handles them.
 - Call `ready()` explicitly only when you need provisioning results such as the preview URL or opened ports.
 - API notebook creates and forks are ephemeral by default. `persistent: true` requires an entitled account.
 - Use `NotebookData.runtimeUrl`, `runtimeUrlProvider`, and `PublicationData.eventStreamUrl` for runtime access.
@@ -370,32 +370,51 @@ try {
 
 MIT
 
-### Publishing without Helfer
+### Publishing apps
 
-Publishing is a platform capability. An API-key client can assign production settings with `notebook.secrets`, discover destinations and owned resources through `notebook.publication.catalog`, and submit its application choices through `prepareApplication`.
+Save your app configuration, prepare a proposal for the apps you want to publish, and submit that proposal after explicit confirmation. Use `notebook.secrets` for production secrets and `notebook.publication.catalog` to discover destinations and available resources.
 
 ```ts
 const notebook = await client.notebook.get('SANDBOX_ID');
-const review = await notebook.publication.prepareApplication({
-  schemaVersion: 1,
-  components: [{
-    id: 'web', kind: 'http-service', root: '.',
-    build: { mode: 'dockerfile', context: '.', dockerfile: { source: 'project', path: 'Dockerfile' } },
-    runtime: { kind: 'http', port: 3333, healthCheck: { path: '/' } },
-    placement: { provider: 'ssh-server', serverId: 'OWNED_SERVER_ID' },
-  }],
-});
-if (!review.review.ready) {
-  console.log(review.review.blockers);
-} else {
-  // Present this exact review and obtain confirmation before executing.
-  const application = await notebook.publication.publishApplication({ reviewId: review.review.id });
-  const current = await notebook.publication.application(application.id);
-  console.log(current.status); // publishing, healthy, failed, or deleted
+try {
+  const configuration = await notebook.publication.updateConfiguration({
+    expectedRevision: 0,
+    operations: [{ op: 'add-app', app: {
+      name: 'Backend', kind: 'http', root: '.',
+      build: { mode: 'dockerfile', context: '.', dockerfile: { source: 'project', path: 'Dockerfile' } },
+      runtime: { mode: 'container', port: 3333, healthCheck: { path: '/' } },
+      destination: { provider: 'ssh-server', serverId: 'OWNED_SERVER_ID' },
+      routing: { mode: 'managed' }, resourceIds: [],
+    } }],
+  });
+  const appIds = [configuration.apps[0].id];
+  const plan = await notebook.publication.prepare({
+    expectedRevision: configuration.revision, appIds,
+  });
+  if (!plan.review.ready) {
+    console.log(plan.review.blockers);
+  } else {
+    // Show this proposal to the user and wait for their confirmation.
+    const result = await notebook.publication.publish({
+      reviewId: plan.review.id, proposal: plan.review.proposal, appIds,
+    });
+    if ('confirmationRequired' in result) {
+      // Show the changes and updated proposal; obtain a new confirmation.
+      console.log(result.changes, result.plan);
+    } else {
+      const current = await notebook.publication.application(result.id);
+      console.log(current.status); // publishing, healthy, partial, failed, or deleted
+    }
+  }
+} finally {
+  notebook.dispose();
 }
-notebook.dispose();
 ```
 
-Core owns validation, source snapshots, review expiry, identity, resource ownership, execution and recovery. The confirmation reference binds the resolved review; another client does not copy source revisions or recreate provider logic. Repeated confirmation of an executed reference returns its existing application. A corrected review retains the publication and address. `retryApplication(id)` asks the platform to revalidate and retry failed components; inspect current state and logs when an outcome is uncertain. `destroyApplication(id)` unpublishes, and resource deletion requires the explicit `deleteResources` option.
+`configuration()` returns saved apps and actual deployment inventory. Configuration edits require `expectedRevision`; omitted apps remain unchanged, and removing an app from configuration does not unpublish it. An existing deployment is adopted explicitly using its exact publication ID.
+
+Preparing or viewing a proposal does not start publishing. Confirmation sends the signed `proposal` unchanged along with its `reviewId` and app selection. Current source is captured when that confirmation is submitted. If material settings changed, `publish()` returns `confirmationRequired` without starting a deployment. Show those changes and obtain confirmation of the updated proposal before trying again. Repeating an already executed confirmation returns its existing operation.
+
+Inspect deployment, runtime and routing outcomes for each selected app; a partial outcome is not full success. `retryApplication(id)` retries failed apps after revalidation. If an outcome is uncertain, inspect status and logs before retrying. `destroyApplication(id)` unpublishes; deleting managed resources additionally requires `deleteResources: true`.
 
-Helfer presents choices, recommendations and explanations, and resumes its own conversation from platform outcomes. Its chat monitor does not own builds or publication state. The CLI exposes the same operations as `application plan`, `application publish`, `application status`, `application retry`, and `application delete`; JSON input is available for multi-component plans.
+Shared managed-resource creation currently starts with one app. After creation, update the resource definition to `reuse` with the catalog resource ID before attaching other apps. Simultaneous first-time shared-resource creation is unsupported.

package/dist/browser/phpsandbox-sdk.esm.js

@@ -15146,17 +15146,6 @@ var PublicationInstance = 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}`);
@@ -15283,24 +15272,28 @@ var NotebookPublication = class {
   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`,
@@ -15314,10 +15307,11 @@ var NotebookPublication = class {
     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)) continue;
+    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),
+        new PublicationInstance(app.publication, this.client, this.notebookId),
         this.client
       ).start();
     }
@@ -15329,11 +15323,6 @@ var NotebookPublication = class {
     }
     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();
-  }
 };
 
 // src/publication/providers/laravel-cloud.ts