@phpsandbox/sdk 0.0.68 → 0.1.2

package/README.md

@@ -23,9 +23,9 @@ const client = PHPSandbox.realtime(token);
 // create() initializes the notebook by default
 const notebook = await client.notebook.create('php');
 
-await notebook.file.write('index.php', '<?php echo "Hello from PHPSandbox";');
+await notebook.files.write('index.php', '<?php echo "Hello from PHPSandbox";');
 
-const process = await notebook.terminal.spawn('php', ['index.php']);
+const process = await notebook.terminals.create({ command: 'php', args: ['index.php'] });
 
 const reader = process.output.getReader();
 let output = '';
@@ -39,7 +39,7 @@ try {
   reader.releaseLock();
 }
 
-await process.exit;
+await process.wait();
 console.log(output.trim());
 
 // close websocket resources when done
@@ -76,14 +76,11 @@ PHPSandbox.rest('token', 'https://api.phpsandbox.io/v1', {
 const client = PHPSandbox.realtime(process.env.PHPSANDBOX_TOKEN!);
 
 const created = await client.notebook.create('laravel');
-const opened = await client.notebook.open('notebook-id');
-await opened.ready();
-
 const fetched = await client.notebook.get('notebook-id');
 await fetched.ready();
 
 const forked = await created.fork();
-await forked.delete();
+await forked.destroy();
 
 const persistent = await client.notebook.create('laravel', {
   title: 'Persistent Laravel',
@@ -101,50 +98,58 @@ console.log(persistentFork.data.policy);
 Notes:
 
 - `create()` and `fork()` initialize automatically.
-- `open()` and `get()` return a notebook instance; call `await notebook.ready()` before using tools.
+- `get()` returns a notebook instance; call `await notebook.ready()` before using tools.
 - API notebook creates and forks are ephemeral by default. `persistent: true` requires an entitled account.
-- Use `NotebookData.runtimeUrl`, `runtimeUrlProvider`, and `DeploymentData.eventStreamUrl` for runtime access.
+- Use `NotebookData.runtimeUrl`, `runtimeUrlProvider`, and `PublicationData.eventStreamUrl` for runtime access.
 
 ## Services At A Glance
 
 Each `NotebookInstance` exposes service clients:
 
-- `notebook.file` (`Filesystem`)
-- `notebook.terminal` (`Terminal`)
+- `notebook.files` (`Filesystem`)
+- `notebook.terminals` (`Terminals`)
 - `notebook.container` (`Container`)
-- `notebook.shell` (`Shell`)
 - `notebook.composer` (`Composer`)
 - `notebook.git` (`Git`)
 - `notebook.lsp` (`Lsp`)
 - `notebook.repl` (`Repl`)
-- `notebook.laravel` (`Laravel`)
 - `notebook.auth` (`Auth`)
-- `notebook.log` (`Log`)
+- `notebook.logs` (`Logs`)
+- `notebook.ports` (`Ports`)
+- `notebook.metrics` (`Metrics`)
 - `notebook.services` (`Services`)
 - `notebook.mail` (`NotebookMail`)
 
 Notes:
 
-- `terminal.spawn()` and `shell.exec()` are part of the current runtime action set. `terminal.start` currently is not.
-- `notebook.repl.eval()` is part of the current runtime action set. `repl.start` is currently not.
-- `notebook.laravel` is exposed by the SDK, but the current runtime action set does not expose Laravel maintenance actions.
+- `terminals.create()` is the TTY-oriented process API; `notebook.exec()` and `notebook.run()` are the native non-TTY process APIs.
+- `notebook.repl.eval()` evaluates PHP without exposing the unsupported `repl.start` action.
 
 ## Common Operations
 
 ### Files
 
 ```ts
-await notebook.file.write('README.md', '# App');
+await notebook.files.write('README.md', '# App');
 
-const raw = await notebook.file.readFile('README.md');
-const text = new TextDecoder().decode(raw);
+await notebook.files.write('archive.zip', byteStream);
+for await (const chunk of notebook.files.readStream('archive.zip')) {
+  consume(chunk);
+}
 
-const files = await notebook.file.find('*.php', {
+const raw = await notebook.files.read('README.md');
+const text = await notebook.files.readText('README.md');
+const excerpt = await notebook.files.readLines('storage/logs/laravel.log', {
+  start: 100,
+  end: 200,
+});
+
+const files = await notebook.files.find('*.php', {
   includes: ['app/**'],
   excludes: ['vendor/**'],
 });
 
-const [hasMore, matches] = await notebook.file.search(
+const [hasMore, matches] = await notebook.files.search(
   { pattern: 'class\\s+User', isRegExp: true },
   { maxResults: 20, includes: ['app/**'], excludes: ['vendor/**'] }
 );
@@ -153,22 +158,27 @@ const [hasMore, matches] = await notebook.file.search(
 ### Terminal
 
 ```ts
-const task = await notebook.terminal.spawn('composer', ['--version']);
+const task = await notebook.terminals.create({ command: 'composer', args: ['--version'] });
 
 task.output.getReader().read().then(({ value }) => {
   console.log(value);
 });
 
-const exitCode = await task.exit;
+const exitCode = await task.wait();
 console.log(exitCode);
 ```
 
 ### Shell
 
 ```ts
-const result = await notebook.shell.exec('php -v');
+const result = await notebook.exec('php -v');
 result.throw();
-console.log(result.output);
+
+const process = notebook.run('php -v', { tty: false });
+for await (const chunk of process.output) {
+  console.log(chunk.source, new TextDecoder().decode(chunk.data));
+}
+(await process.wait()).throw();
 ```
 
 ### Services
@@ -187,17 +197,41 @@ const snapshot = await notebook.services.logs('redis', { tail: 50 });
 console.log(snapshot);
 
 const stream = notebook.services.logs('redis', { follow: true, tail: 25 });
-const reader = stream.output.getReader();
+const reader = stream.getReader();
 const chunk = await reader.read();
 console.log(chunk.value);
-await stream.stop();
+await reader.cancel();
+```
+
+### Runtime observability
+
+```ts
+const currentPorts = await notebook.ports.list();
+const currentMetrics = await notebook.metrics.current();
+
+for await (const sample of notebook.metrics.watch({ signal })) {
+  console.log(sample.cpu, sample.memory, sample.disk);
+}
+
+for await (const ports of notebook.ports.watch({ signal })) {
+  console.log(ports);
+}
+
+for await (const entry of notebook.logs.follow({ signal })) {
+  console.log(entry.timestamp, entry.source, entry.message);
+}
 ```
 
 ### Composer
 
 ```ts
-await notebook.composer.install({ noInteraction: true });
-await notebook.composer.require({ packages: ['monolog/monolog'] });
+const install = notebook.composer.install();
+for await (const chunk of install.output) {
+  console.log(chunk.source, new TextDecoder().decode(chunk.data));
+}
+(await install.wait()).throw();
+
+(await notebook.composer.require({ packages: ['monolog/monolog'] }).wait()).throw();
 
 const installed = await notebook.composer.packages();
 console.log(installed.map((pkg) => pkg.name));
@@ -279,7 +313,7 @@ const disposeConnect = notebook.onDidConnect(() => {
   console.log('connected');
 });
 
-const disposeFs = notebook.file.watch(
+const disposeFs = notebook.files.watch(
   '/app',
   { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
   (change) => {
@@ -298,7 +332,7 @@ disposeFs.dispose();
 import { ApiError, FilesystemError, FilesystemErrorType } from '@phpsandbox/sdk';
 
 try {
-  await notebook.file.readFile('/does-not-exist.php');
+  await notebook.files.read('/does-not-exist.php');
 } catch (error) {
   if (error instanceof FilesystemError && error.name === FilesystemErrorType.FileNotFound) {
     console.error('Missing file');

package/dist/auth.d.ts

@@ -7,6 +7,5 @@ export interface AuthActions {
 export default class Auth {
     protected okra: NotebookInstance;
     constructor(okra: NotebookInstance);
-    logout(): void;
     login(runtimeUrl: string): Promise<boolean>;
 }

package/dist/auth.js

@@ -2,9 +2,6 @@ export default class Auth {
     constructor(okra) {
         this.okra = okra;
     }
-    logout() {
-        this.okra.dispose();
-    }
     login(runtimeUrl) {
         const runtimeTicket = new URL(runtimeUrl).searchParams.get('ticket');
         if (runtimeTicket === null || runtimeTicket === '') {

package/dist/beacon/index.d.ts

@@ -1,6 +1,7 @@
 import { Disposable } from '../types.js';
 import { BeaconActions, BeaconEvents, BeaconOptions, DebugInfo, ConsoleEvent, BeaconErrorEvent, DebugRequest, DebugResult, ScreenshotRequest, ScreenshotResult, FetchRequest, FetchResult } from './types.js';
 import { Navigator } from './navigator.js';
+import type { NotebookInstance } from '../index.js';
 export * from './types.js';
 export { Navigator } from './navigator.js';
 /**
@@ -166,6 +167,7 @@ export declare class Beacon implements BeaconActions {
  * Factory function to create a beacon instance for an iframe
  */
 export declare function createBeacon(iframe: HTMLIFrameElement, options?: BeaconOptions): Beacon;
+export declare function connectBeacon(notebook: NotebookInstance, iframe: HTMLIFrameElement, options?: BeaconOptions): Promise<Beacon>;
 /**
  * Check if the current environment supports the Beacon SDK
  */

package/dist/beacon/index.js

@@ -530,6 +530,11 @@ export class Beacon {
 export function createBeacon(iframe, options) {
     return new Beacon(iframe, options);
 }
+export async function connectBeacon(notebook, iframe, options) {
+    const result = await notebook.ready();
+    iframe.src = result.data.previewUrl;
+    return createBeacon(iframe, options);
+}
 /**
  * Check if the current environment supports the Beacon SDK
  */