@phpsandbox/sdk 0.6.0-canary.0 → 0.6.0-canary.10

package/README.md

@@ -57,7 +57,7 @@ PHPSandbox.rest('token', 'https://api.phpsandbox.io/v1', {
 
 ## App server integration
 
-Apps hosted on PHPSandbox can use one environment-scoped identity for Customers and Payments:
+Apps hosted on PHPSandbox can use one environment-scoped identity for Customers, Payments, and feedback:
 
 ```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
@@ -76,9 +76,18 @@ const checkout = await platform.payments.checkout({
   successPath: '/thanks',
   cancelPath: '/account',
 });
+await platform.feedback.submit({
+  type: 'question',
+  message: feedback.message,
+  author: { externalId: account.customerExternalId },
+}, { idempotencyKey: feedback.id });
 ```
 
-Persist an opaque UUID on each app account for its external customer identity; separate databases must not reuse sequential IDs. Initialize this client only on the app server. It reads the provisioned app configuration and exposes only app runtime capabilities, without notebook or organization administration. Production uses its own identity and never falls back to development. Select `{ mode: 'test' }` once for an intentional sandbox run. Runtimes without `process.env` can supply server bindings through `{ env }`.
+Persist an opaque UUID on each app account for its external customer identity; separate databases must not reuse sequential IDs. Initialize this client only on the app server. It reads the provisioned app configuration and exposes only connected app runtime capabilities, without notebook or organization administration. Production uses its own identity and never falls back to development. Use `{ mode: 'test' }` only in development. Runtimes without `process.env` can supply server bindings through `{ env }`.
+
+Connect feedback before publishing using your builder client: `await client.feedback.forProject('PROJECT_ID').provision('live')`. Use `test` for development previews. The app credential can submit feedback but cannot read the seller inbox or change feedback status. Save messages in your app first and forward with a stable idempotency key so a temporary delivery failure does not lose the buyer's message or create duplicates.
+
+The SDK is optional: any backend, including PHP, can send the same JSON payload to `POST /v1/platform/feedback/runtime` with the environment's app credential in `Authorization: Bearer APP_TOKEN` and a stable `Idempotency-Key` header. Keep that credential on the server; buyers sign in to your app and do not need a PHPSandbox account.
 
 Applications can configure their own organization conversion stages and one event follow-up. Configuration never activates a journey:
 
@@ -172,7 +181,6 @@ Each `NotebookInstance` exposes service clients:
 - `notebook.auth` (`Auth`)
 - `notebook.services` (`Services`)
 - `notebook.mail` (`NotebookMail`)
-- `notebook.feedback` (`Feedback`)
 
 Notes:
 
@@ -209,6 +217,32 @@ const [hasMore, matches] = await notebook.files.search(
 );
 ```
 
+`files.download()` returns a `ReadableStream<Uint8Array>` containing the notebook ZIP.
+Read it incrementally or pipe it to a writable stream:
+
+```ts
+const controller = new AbortController();
+const archive = notebook.files.download({
+  include: ['src/**'],
+  exclude: ['vendor/**'],
+  signal: controller.signal,
+});
+
+for await (const chunk of archive) {
+  await consume(chunk);
+}
+```
+
+Downloads use HTTP for both realtime and REST clients and require the runtime's
+`POST /api/v1/notebooks/{notebook}/runtime/files/download` endpoint. Reading starts
+the request; cancelling the stream, aborting its signal, or disposing the notebook
+stops the transfer. Failures reject stream reads and are not retried after bytes
+have started arriving.
+
+**Breaking change in 0.6.0-canary.4:** downloads no longer return a `Blob` or accept
+`onChunk`. If you need a Blob, explicitly collect the archive with
+`await new Response(notebook.files.download()).blob()`; this buffers the ZIP in memory.
+
 ### Terminal
 
 ```ts
@@ -375,24 +409,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
-await notebook.feedback.configure({
+// Feedback uses the same API token as the rest of the SDK.
+// 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.
@@ -450,42 +499,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();
 }
 ```
 
@@ -497,6 +542,21 @@ Inspect deployment, runtime and routing outcomes for each selected app; a partia
 
 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.
 
+#### Custom domains
+
+For a healthy Laravel Cloud publication, choose the DNS setup when creating the domain:
+
+```ts
+const publication = await client.publications.get('PUBLICATION_ID');
+const domain = await publication.domains.create('app.example.com', {
+  cloudflareStrategy: 'dns_proxy',
+  allowDowntime: false,
+});
+console.log(domain.dnsInstructions);
+```
+
+Use `none` for another DNS provider, `dns` for Cloudflare DNS only, or `dns_proxy` for Cloudflare's orange-cloud proxy. `allowDowntime: false` prepares verification before traffic moves; `true` allows routing first. Omitted options preserve the existing `none` / uninterrupted defaults. These optional settings require an API version that supports domain DNS and transfer choices. Existing provider domains are inspected rather than reconfigured.
+
 #### Browser publishing streams through your backend
 
 Keep service-account credentials on your server. After authorizing project access and checking the requested publishing attempt, open the original SSE bytes with `publication.stream()`. Return the SDK's standard `Response` directly from your framework:
@@ -534,3 +594,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`.

package/dist/app.d.ts

@@ -1,6 +1,7 @@
 import type { Client } from './index.js';
 import { CustomerRuntime } from './customers.js';
 import { PaymentRuntime, type PaymentMode } from './payments.js';
+import { FeedbackRuntime } from './feedback.js';
 export interface AppRuntimeOptions {
     /** Defaults to live in production and test otherwise. There is no fallback between modes. */
     mode?: PaymentMode;
@@ -17,5 +18,6 @@ export declare class AppRuntime {
     readonly mode: PaymentMode;
     readonly customers: CustomerRuntime;
     readonly payments: PaymentRuntime;
+    readonly feedback: FeedbackRuntime;
     constructor(client: Client, token: string, mode: PaymentMode);
 }

package/dist/app.js

@@ -1,5 +1,6 @@
 import { CustomerRuntime } from './customers.js';
 import { PaymentRuntime } from './payments.js';
+import { FeedbackRuntime } from './feedback.js';
 export function resolveAppConfiguration(options) {
     if (typeof window !== 'undefined' && typeof document !== 'undefined') {
         throw new Error('Application credentials must only be used on a trusted server.');
@@ -9,7 +10,7 @@ export function resolveAppConfiguration(options) {
     const token = environment[`PHPSANDBOX_APP_${mode.toUpperCase()}_TOKEN`];
     const url = environment.PHPSANDBOX_APP_API_URL;
     if (!token || !/^happ_[a-f0-9]{64}$/.test(token) || !url) {
-        throw new Error(`Connect your app's ${mode === 'live' ? 'production' : 'development'} platform environment before using Customers or Payments.`);
+        throw new Error(`Connect your app's ${mode === 'live' ? 'production' : 'development'} platform environment before using platform services.`);
     }
     return { mode, token, url };
 }
@@ -19,5 +20,6 @@ export class AppRuntime {
         this.mode = mode;
         this.customers = new CustomerRuntime(client);
         this.payments = new PaymentRuntime(client, { token, mode });
+        this.feedback = new FeedbackRuntime(client);
     }
 }