@phpsandbox/sdk 0.1.6 → 0.1.10

package/README.md

@@ -12,6 +12,8 @@ Node.js `>=18` is required. This package is ESM-only; use `import` rather than `
 
 ## Quick Start
 
+Save this as `quickstart.mjs` and run `node quickstart.mjs` after setting `PHPSANDBOX_TOKEN`. Expected output: `Hello from PHPSandbox`. The example creates and deletes a temporary plain PHP notebook.
+
 ```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
 
@@ -19,36 +21,24 @@ const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
 
 const client = PHPSandbox.realtime(token);
+const notebook = await client.notebook.create('standard');
 
-// create() initializes the notebook by default
-const notebook = await client.notebook.create('php');
-
-await notebook.files.write('index.php', '<?php echo "Hello from PHPSandbox";');
-
-const process = await notebook.terminals.create({ command: 'php', args: ['index.php'] });
-
-const reader = process.output.getReader();
-let output = '';
-try {
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    output += value;
-  }
-} finally {
-  reader.releaseLock();
-}
-
-await process.wait();
-console.log(output.trim());
+await notebook.files.write('hello.php', '<?php echo "Hello from PHPSandbox";');
+const result = await notebook.exec('php', ['hello.php']);
+if (result.exitCode !== 0) throw new Error(result.stderr || result.output);
+console.log(result.stdout.trim());
 
-// close websocket resources when done
+await notebook.destroy();
 notebook.dispose();
 ```
 
 ## Authentication
 
-Use an API token:
+Sign in to PHPSandbox and open **API keys**. Create a named key and copy it when shown; it cannot be revealed again. API-key access currently requires SDK access to be enabled for your account. Creating or forking notebooks requires an active subscription and available notebook capacity.
+
+Keys from this screen grant account-level notebook read and write access. Keep them in a server environment variable or secret store. Never place them in browser code, notebooks, URLs, logs, or source control. To rotate, create a replacement, update your application, verify it, then revoke the old key.
+
+Use an API key:
 
 ```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
@@ -61,7 +51,6 @@ Explicit realtime and REST clients:
 ```ts
 PHPSandbox.realtime('token', 'https://api.phpsandbox.io/v1', {
   debug: false,
-  startClosed: true,
 });
 
 // Use explicit request/response runtime actions without a websocket.
@@ -77,7 +66,6 @@ const client = PHPSandbox.realtime(process.env.PHPSANDBOX_TOKEN!);
 
 const created = await client.notebook.create('laravel');
 const fetched = await client.notebook.get('notebook-id');
-await fetched.ready();
 
 const forked = await created.fork();
 await forked.destroy();
@@ -97,8 +85,8 @@ console.log(persistentFork.data.policy);
 
 Notes:
 
-- `create()` and `fork()` initialize automatically.
-- `get()` returns a notebook instance; call `await notebook.ready()` before using tools.
+- Runtime actions wait for the sandbox to become ready before Okra 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.
 
@@ -108,16 +96,13 @@ Each `NotebookInstance` exposes service clients:
 
 - `notebook.files` (`Filesystem`)
 - `notebook.terminals` (`Terminals`)
-- `notebook.container` (`Container`)
+- `notebook.runtime` (lifecycle, configuration, logs, metrics, and ports)
 - `notebook.composer` (`Composer`)
 - `notebook.git` (`Git`)
 - `notebook.integrations` (`SandboxIntegrationApi`)
 - `notebook.lsp` (`Lsp`)
 - `notebook.repl` (`Repl`)
 - `notebook.auth` (`Auth`)
-- `notebook.logs` (`Logs`)
-- `notebook.ports` (`Ports`)
-- `notebook.metrics` (`Metrics`)
 - `notebook.services` (`Services`)
 - `notebook.mail` (`NotebookMail`)
 - `notebook.feedback` (`Feedback`)
@@ -174,13 +159,14 @@ console.log(exitCode);
 
 ```ts
 const result = await notebook.exec('php -v');
-result.throw();
+if (result.exitCode !== 0) throw new Error(result.stderr || 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();
+const processResult = await process.wait();
+if (processResult.exitCode !== 0) throw new Error(processResult.stderr || processResult.output);
 ```
 
 ### Services
@@ -208,18 +194,18 @@ await reader.cancel();
 ### Runtime observability
 
 ```ts
-const currentPorts = await notebook.ports.list();
-const currentMetrics = await notebook.metrics.current();
+const currentPorts = await notebook.runtime.ports.list();
+const currentMetrics = await notebook.runtime.metrics.current();
 
-for await (const sample of notebook.metrics.watch({ signal })) {
+for await (const sample of notebook.runtime.metrics.watch({ signal })) {
   console.log(sample.cpu, sample.memory, sample.disk);
 }
 
-for await (const ports of notebook.ports.watch({ signal })) {
+for await (const ports of notebook.runtime.ports.watch({ signal })) {
   console.log(ports);
 }
 
-for await (const entry of notebook.logs.follow({ signal })) {
+for await (const entry of notebook.runtime.logs.follow({ signal })) {
   console.log(entry.timestamp, entry.source, entry.message);
 }
 ```
@@ -227,13 +213,15 @@ for await (const entry of notebook.logs.follow({ signal })) {
 ### Composer
 
 ```ts
-const install = notebook.composer.install();
+const install = notebook.composer.run('install');
 for await (const chunk of install.output) {
   console.log(chunk.source, new TextDecoder().decode(chunk.data));
 }
-(await install.wait()).throw();
+const installResult = await install.wait();
+if (installResult.exitCode !== 0) throw new Error(installResult.stderr || installResult.output);
 
-(await notebook.composer.require({ packages: ['monolog/monolog'] }).wait()).throw();
+const requireResult = await notebook.composer.run('require', { packages: ['monolog/monolog'] }).wait();
+if (requireResult.exitCode !== 0) throw new Error(requireResult.stderr || requireResult.output);
 
 const installed = await notebook.composer.packages();
 console.log(installed.map((pkg) => pkg.name));
@@ -338,7 +326,7 @@ const disposeConnect = notebook.onDidConnect(() => {
   console.log('connected');
 });
 
-const disposeFs = notebook.files.watch(
+const disposeFs = await notebook.files.watch(
   '/app',
   { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
   (change) => {
@@ -354,15 +342,19 @@ disposeFs.dispose();
 ## Error Handling
 
 ```ts
-import { ApiError, FilesystemError, FilesystemErrorType } from '@phpsandbox/sdk';
+import { RemoteError, TransportError } from '@phpsandbox/sdk';
 
 try {
   await notebook.files.read('/does-not-exist.php');
 } catch (error) {
-  if (error instanceof FilesystemError && error.name === FilesystemErrorType.FileNotFound) {
+  if (RemoteError.is(error, 'FileNotFound')) {
     console.error('Missing file');
-  } else if (error instanceof ApiError) {
-    console.error(error.status, error.body);
+  } else if (RemoteError.isValidation(error)) {
+    console.error(error.details.errors);
+  } else if (error instanceof RemoteError) {
+    console.error(error.source, error.status, error.code, error.message);
+  } else if (error instanceof TransportError) {
+    console.error(error.code, error.cause);
   } else {
     throw error;
   }
@@ -371,13 +363,13 @@ try {
 
 ## Browser/CDN Usage
 
-See `docs/cdn-usage.md` for ESM and script-tag examples.
+See [Browser usage](docs/cdn-usage.md) for ESM and script-tag examples.
 
 ## More Docs
 
-- Getting started walkthrough: `docs/getting-started.md`
-- API overview: `docs/api-summary.md`
-- Examples: `examples/README.md`
+- Getting started walkthrough: [Getting started](docs/getting-started.md)
+- API overview: [API overview](docs/api-summary.md)
+- Examples: [Examples](examples/README.md)
 
 ## Support
 

package/dist/beacon/index.d.ts

@@ -1,9 +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';
 /**
  * BeaconError for beacon-specific errors
  */
@@ -163,11 +161,7 @@ export declare class Beacon implements BeaconActions {
      */
     dispose(): void;
 }
-/**
- * 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>;
+export declare function connectBeacon(iframe: HTMLIFrameElement, options?: BeaconOptions): Promise<Beacon>;
 /**
  * Check if the current environment supports the Beacon SDK
  */

package/dist/beacon/index.js

@@ -3,7 +3,6 @@ import { timeout } from '../utils/promise.js';
 import { retry } from '../utils/retry.js';
 import { Navigator } from './navigator.js';
 export * from './types.js';
-export { Navigator } from './navigator.js';
 /**
  * Browser environment check
  */
@@ -89,6 +88,9 @@ export class Beacon {
                 if (event.source !== this.iframe.contentWindow) {
                     return;
                 }
+                if (this.options.targetOrigin !== '*' && event.origin !== this.options.targetOrigin) {
+                    return;
+                }
                 const message = event.data;
                 if (!message || typeof message !== 'object' || !message.type) {
                     return;
@@ -151,8 +153,7 @@ export class Beacon {
             timestamp: Date.now(),
             id: this.generateId(),
         };
-        this.iframe.contentWindow.postMessage(establishMessage, '*', // Safe for channel establishment
-        [this.messageChannel.port2] // Transfer the port
+        this.iframe.contentWindow.postMessage(establishMessage, this.options.targetOrigin, [this.messageChannel.port2] // Transfer the port
         );
         if (this.options.debug) {
             console.log('[Beacon SDK] Channel establishment message sent');
@@ -524,16 +525,16 @@ export class Beacon {
         this.readyPromise = null;
     }
 }
-/**
- * Factory function to create a beacon instance for an iframe
- */
-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);
+export async function connectBeacon(iframe, options) {
+    const beacon = new Beacon(iframe, options);
+    try {
+        await beacon.start();
+    }
+    catch (error) {
+        beacon.dispose();
+        throw error;
+    }
+    return beacon;
 }
 /**
  * Check if the current environment supports the Beacon SDK

package/dist/beacon/navigator.d.ts

@@ -11,7 +11,7 @@ export interface NavigatorActions {
     goForward(): Promise<NavigationResult>;
     canGoBack: boolean;
     canGoForward: boolean;
-    refresh(): Promise<void>;
+    reload(): Promise<void>;
     getCurrentUrl(): URL;
     on<K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void): Disposable;
 }
@@ -46,10 +46,6 @@ export interface HistoryInfoResponse {
     canGoBack: boolean;
     canGoForward: boolean;
 }
-export interface Navigator extends NavigatorActions {
-    on<K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void): Disposable;
-    once<K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void): void;
-}
 /**
  * SDK Navigator implementation with internal history management
  */
@@ -61,7 +57,7 @@ export declare class Navigator implements NavigatorActions {
     private currentIndex;
     private _canGoBack;
     private _canGoForward;
-    constructor(onEvent: <K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void) => Disposable, onceEvent: <K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void) => void, beacon: Beacon);
+    constructor(onEvent: <K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void) => Disposable, onceEvent: <K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void) => Disposable, beacon: Beacon);
     /**
      * Navigate to a URL using internal history management
      */
@@ -97,44 +93,20 @@ export declare class Navigator implements NavigatorActions {
      * Get current URL from internal history
      */
     getCurrentUrl(): URL;
-    /**
-     * Get the complete history array
-     */
-    getHistory(): readonly string[];
-    /**
-     * Get current history index
-     */
-    getCurrentIndex(): number;
-    /**
-     * Check if can go back synchronously
-     */
-    canGoBackSync(): boolean;
-    /**
-     * Check if can go forward synchronously
-     */
-    canGoForwardSync(): boolean;
     /**
      * Emit history change event
      */
     private emitHistoryChange;
     /**
-     * Push a new state to internal history (legacy method for compatibility)
-     */
-    pushState(url: string): Promise<void>;
-    /**
-     * Replace current state in internal history (legacy method for compatibility)
-     */
-    replaceState(url: string): Promise<void>;
-    /**
-     * Get the current history length
+     * Get comprehensive history information
      */
-    getHistoryLength(): Promise<number>;
+    getHistoryInfo(): Promise<HistoryInfoResponse>;
     /**
-     * Get the current history state (always null since we don't store state)
+     * Listen for navigator events
      */
-    getHistoryState(): Promise<unknown>;
+    on<K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void): Disposable;
     /**
-     * Get comprehensive history information
+     * Listen for navigator events (once)
      */
-    getHistoryInfo(): Promise<HistoryInfoResponse>;
+    once<K extends keyof NavigatorEvents>(event: K, handler: (payload: NavigatorEvents[K]) => void): Disposable;
 }

package/dist/beacon/navigator.js

@@ -142,30 +142,6 @@ export class Navigator {
         }
         return new URL('about:blank');
     }
-    /**
-     * Get the complete history array
-     */
-    getHistory() {
-        return [...this.urlHistory];
-    }
-    /**
-     * Get current history index
-     */
-    getCurrentIndex() {
-        return this.currentIndex;
-    }
-    /**
-     * Check if can go back synchronously
-     */
-    canGoBackSync() {
-        return this.currentIndex > 0;
-    }
-    /**
-     * Check if can go forward synchronously
-     */
-    canGoForwardSync() {
-        return this.currentIndex < this.urlHistory.length - 1;
-    }
     /**
      * Emit history change event
      */
@@ -181,43 +157,6 @@ export class Navigator {
             });
         }
     }
-    /**
-     * Push a new state to internal history (legacy method for compatibility)
-     */
-    async pushState(url) {
-        // For compatibility, treat this as a navigation
-        this.visit(url);
-    }
-    /**
-     * Replace current state in internal history (legacy method for compatibility)
-     */
-    async replaceState(url) {
-        if (this.currentIndex >= 0 && this.currentIndex < this.urlHistory.length) {
-            // Replace the current URL in history
-            this.urlHistory[this.currentIndex] = url;
-            if (!this.beacon) {
-                throw new Error('Beacon reference not set');
-            }
-            this.beacon.navigate(url);
-            this.emitHistoryChange(url, 'replace');
-        }
-        else {
-            // If no current history, treat as push
-            this.visit(url);
-        }
-    }
-    /**
-     * Get the current history length
-     */
-    async getHistoryLength() {
-        return this.urlHistory.length;
-    }
-    /**
-     * Get the current history state (always null since we don't store state)
-     */
-    async getHistoryState() {
-        return null;
-    }
     /**
      * Get comprehensive history information
      */
@@ -240,6 +179,6 @@ export class Navigator {
      * Listen for navigator events (once)
      */
     once(event, handler) {
-        this.onceEvent(event, handler);
+        return this.onceEvent(event, handler);
     }
 }