@phpsandbox/sdk 0.6.0-canary.5 → 0.6.0-canary.7

package/README.md

@@ -172,7 +172,6 @@ Each `NotebookInstance` exposes service clients:
 - `notebook.auth` (`Auth`)
 - `notebook.services` (`Services`)
 - `notebook.mail` (`NotebookMail`)
-- `notebook.feedback` (`Feedback`)
 
 Notes:
 
@@ -401,27 +400,39 @@ await notebook.mail.delete(mail.hash);
 await notebook.mail.disable();
 ```
 
+### Product features
+
+Projects own the product lifecycle. Address Customers, Payments, feedback, and publishing with an existing project ID; creating a standalone compute sandbox does not create a project.
+
+This replaces `notebook.feedback`, `notebook.payments`, `notebook.publication`, and the `forNotebook` helpers. Use a project ID explicitly; sandbox IDs are not aliases for projects.
+
+```ts
+const customers = client.customers.forProject('PROJECT_ID');
+const payments = client.payments.forProject('PROJECT_ID');
+const publishing = client.publications.forProject('PROJECT_ID');
+```
+
 ### Feedback
 
 ```ts
 // Feedback uses the same API token as the rest of the SDK.
-// You can also address it directly with client.feedback.forProject(projectId)
-// or client.feedback.forNotebook(notebookId), without fetching a notebook.
-await notebook.feedback.configure({
+// Product features require an existing project ID, not a sandbox ID.
+const projectFeedback = client.feedback.forProject('PROJECT_ID');
+await projectFeedback.configure({
   widget: {
     targets: ['preview', 'publication'],
     types: ['bug', 'suggestion', 'question'],
   },
 });
 
-const feedback = await notebook.feedback.submit({
+const feedback = await projectFeedback.submit({
   type: 'bug',
   message: 'Saving the profile failed.',
   author: { externalId: 'customer-42', email: 'ada@example.com' },
   context: { url: 'https://app.example.com/profile', path: '/profile' },
 });
 
-await notebook.feedback.update(feedback.id, { status: 'resolved' });
+await projectFeedback.update(feedback.id, { status: 'resolved' });
 ```
 
 The server-side SDK uses the same PHPSandbox API token as the rest of the sandbox. Set `widget: null` to remove the optional popout without disabling API ingestion.
@@ -479,42 +490,38 @@ MIT
 
 ### Publishing apps
 
-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.
+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 `client.publications.forProject(projectId).catalog` to discover destinations and available resources.
 
 ```ts
-const notebook = await client.notebook.get('SANDBOX_ID');
-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,
+const publisher = client.publications.forProject('PROJECT_ID');
+const configuration = await publisher.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 publisher.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 publisher.publish({
+    reviewId: plan.review.id, proposal: plan.review.proposal, appIds,
   });
-  if (!plan.review.ready) {
-    console.log(plan.review.blockers);
+  if ('confirmationRequired' in result) {
+    // Show the changes and updated proposal; obtain a new confirmation.
+    console.log(result.changes, result.plan);
   } 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
-    }
+    const current = await publisher.application(result.id);
+    console.log(current.status); // publishing, healthy, partial, failed, or deleted
   }
-} finally {
-  notebook.dispose();
 }
 ```
 
@@ -563,3 +570,23 @@ for await (const event of readPublicationStream(response)) {
 ```
 
 `readPublicationStream` also accepts a `ReadableStream<Uint8Array>`. By default, it rejects EOF without a final result (including empty streams). Use `{ requireResult: false }` only when deliberately consuming a stream fragment. It validates recognized event payloads, throws for server error events, and ignores unknown event names and heartbeat comments. Ending iteration early cancels the stream; aborting the fetch interrupts a pending read. Disconnecting observation does not cancel the server-side deployment. `PublicationRun.events()` uses this same parser.
+
+### App access
+
+Configure preview access and inherited access for apps published through the managed edge:
+
+```ts
+await notebook.preview.configure({ mode: 'password', password: 'a-long-private-password' });
+await notebook.preview.configure({
+  mode: 'email',
+  allowedEmails: ['person@example.com', '*@company.test'],
+});
+await notebook.preview.configure({ mode: 'external', authorizationUrl: 'https://auth.example.com/access' });
+await notebook.preview.configure({ mode: 'public' });
+```
+
+Email mode presents email and code forms on the app's domain. Supply between 1 and 100 exact email addresses or domain rules such as `*@company.test`. Domain rules match that exact domain, excluding subdomains. The platform sends and verifies the codes; no custom verification service or callback configuration is required. Protected mode changes rotate the access version, invalidating previous grants and pending codes. `preview.get()` includes the current mode and email rules.
+
+External mode redirects visitors to the configured HTTPS URL with the app URL in `returnTo`. Your service decides whether to grant access, obtains an access URL through the authenticated API, and returns the visitor using that opaque URL. Keep API credentials on your server and validate return targets. `preview.get(url)` returns both a clean `url` and a credentialed `accessUrl`; open `accessUrl` without reconstructing it.
+
+**Breaking change:** Use `configure({ mode: 'password', password })` instead of `setPassword()` and `configure({ mode: 'public' })` instead of `disable()`; the two older methods and `SetNotebookPreviewInput` have been removed. Access responses now require `mode`, with email rules or an authorization URL required for the corresponding mode. Publication password updates also require `password`.