@phpsandbox/sdk 0.3.0 → 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,40 +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 `prepare`.
+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 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 review = await notebook.publication.prepare({
-  expectedRevision: configuration.revision, appIds: [configuration.apps[0].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.publish({ reviewId: review.review.id });
-  const current = await notebook.publication.application(application.id);
-  console.log(current.status); // publishing, healthy, partial, 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 apps; 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.
 
-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.
+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.
 
-`configuration()` is the authoritative saved App configuration and deployment inventory. Changes use explicit revision-checked operations; adding an app preserves omitted apps. Review and confirm use `prepare({ expectedRevision, appIds? })` and `publish({ reviewId })`. The provider-input publishing contract and `PublicationInstance.publish()` have been removed. Inspect per-app reviewed source and route state; a workspace digest includes uncommitted changes, while a native Git destination commits and pushes that workspace before building. The commit reported at review is the last synced commit, not a promise of the final prepared build commit.
+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`.
 
-Shared managed-resource creation currently starts with one app. After creation, update the resource definition to `reuse` with its actual catalog inventory ID, then attach further apps. Simultaneous first-time shared-resource provisioning is not supported. Historical deployments require explicit adoption by their exact publication ID; new publishing always creates a saved App.
+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/package.json

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