@phpsandbox/sdk 0.0.51 → 0.0.53

package/dist/terminal.js

@@ -16,13 +16,13 @@ export default class Terminal {
         return this.okra.invoke('terminal.create', input);
     }
     onStarted(handler) {
-        this.okra.listen('terminal.started', handler);
+        return this.okra.listen('terminal.started', handler);
     }
     resize(id, size) {
         return this.okra.invoke('terminal.resize', { id, width: size[0], height: size[1] });
     }
     onOutput(id, handler) {
-        this.okra.listen(`terminal.output.${id}`, handler);
+        return this.okra.listen(`terminal.output.${id}`, handler);
     }
     input(id, input) {
         return Promise.resolve(this.okra.send('terminal.input', { id, input }));
@@ -32,38 +32,55 @@ export default class Terminal {
     }
     async attach(id, opts) {
         const handle = this.processHandle(id, opts?.abortSignal);
-        const task = await this.okra.invoke('terminal.attach', {
-            id,
-            replayHistory: opts?.replayHistory,
-        }, { abortSignal: opts?.abortSignal });
-        if (!task) {
+        try {
+            const task = await this.okra.invoke('terminal.attach', {
+                id,
+                replayHistory: opts?.replayHistory,
+            }, { abortSignal: opts?.abortSignal });
+            if (!task) {
+                handle.dispose();
+                return false;
+            }
+            return {
+                ...handle.process,
+                ...task,
+            };
+        }
+        catch (error) {
             handle.dispose();
-            return false;
+            throw error;
         }
-        return {
-            ...handle.process,
-            ...task,
-        };
     }
     async spawn(command, args, opts) {
         const id = opts?.id || nanoid();
         const handle = this.processHandle(id, opts?.abortSignal);
         const { abortSignal, ...otherOpts } = opts ?? {};
-        const result = await this.okra.invoke('terminal.spawn', {
-            command: [command, ...args],
-            opts: {
-                id,
-                ...otherOpts,
-            },
-        }, { abortSignal });
-        return {
-            ...handle.process,
-            ...result,
-        };
+        try {
+            const result = await this.okra.invoke('terminal.spawn', {
+                command: [command, ...args],
+                opts: {
+                    id,
+                    ...otherOpts,
+                },
+            }, { abortSignal });
+            return {
+                ...handle.process,
+                ...result,
+            };
+        }
+        catch (error) {
+            handle.dispose();
+            throw error;
+        }
     }
     processHandle(id, abortSignal) {
         const disposables = new Set();
+        let abortHandler;
         const dispose = () => {
+            if (abortHandler) {
+                abortSignal?.removeEventListener('abort', abortHandler);
+                abortHandler = undefined;
+            }
             for (const disposable of disposables) {
                 disposable.dispose();
             }
@@ -140,8 +157,11 @@ export default class Terminal {
         const resize = (dimensions) => {
             this.okra.invoke('terminal.resize', { id, width: dimensions.cols, height: dimensions.rows });
         };
-        if (abortSignal) {
-            abortSignal.addEventListener('abort', kill);
+        if (abortSignal && !abortSignal.aborted) {
+            abortHandler = () => {
+                void kill();
+            };
+            abortSignal.addEventListener('abort', abortHandler, { once: true });
         }
         return {
             process: {
@@ -155,4 +175,3 @@ export default class Terminal {
         };
     }
 }
-//# sourceMappingURL=terminal.js.map

package/dist/types.d.ts

@@ -13,4 +13,3 @@ export declare class PHPSandboxError extends ErrorEvent {
 export interface Disposable {
     dispose: () => void;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -13,4 +13,3 @@ export class RateLimitError extends ErrorEvent {
 }
 export class PHPSandboxError extends ErrorEvent {
 }
-//# sourceMappingURL=types.js.map

package/dist/utils/disposable.d.ts

@@ -4,4 +4,3 @@ export declare class NamedDisposable implements Disposable {
     add(key: string, disposable: Disposable | (() => Disposable)): void;
     dispose(): void;
 }
-//# sourceMappingURL=disposable.d.ts.map

package/dist/utils/disposable.js

@@ -17,4 +17,3 @@ export class NamedDisposable {
         this.disposables.clear();
     }
 }
-//# sourceMappingURL=disposable.js.map

package/dist/utils/promise.d.ts

@@ -14,4 +14,3 @@ export declare const timeout: <T>(prom: Promise<T>, time: number) => Promise<T>;
  * @returns A wrapped function that memoizes the first execution
  */
 export declare const once: <T>(fn: () => Promise<T>) => (() => Promise<T>);
-//# sourceMappingURL=promise.d.ts.map

package/dist/utils/promise.js

@@ -24,4 +24,3 @@ export const once = (fn) => {
     let result = null;
     return () => result || (result = fn());
 };
-//# sourceMappingURL=promise.js.map

package/dist/utils/retry.d.ts

@@ -9,4 +9,3 @@ export interface RetryOptions {
 type RetryBail = (error?: unknown) => never;
 export declare function retry<T>(fn: (bail: RetryBail, attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
 export {};
-//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.js

@@ -43,4 +43,3 @@ export async function retry(fn, options = {}) {
     }
     throw lastError;
 }
-//# sourceMappingURL=retry.js.map

package/dist/utils/websocket.d.ts

@@ -1,2 +1 @@
 export declare const describeWebSocketEvent: (event: unknown) => string;
-//# sourceMappingURL=websocket.d.ts.map

package/dist/utils/websocket.js

@@ -84,4 +84,3 @@ export const describeWebSocketEvent = (event) => {
     }
     return parts.length > 0 ? parts.join(' | ') : 'Unknown websocket event';
 };
-//# sourceMappingURL=websocket.js.map

package/docs/api-summary.md

@@ -0,0 +1,136 @@
+# PHPSandbox SDK API Summary
+
+This is a quick reference for the current SDK surface.
+
+## Top-Level Client
+
+```ts
+import { PHPSandbox } from '@phpsandbox/sdk';
+
+const client = new PHPSandbox(token, 'https://api.phpsandbox.io/v1', {
+  debug: false,
+  startClosed: true,
+});
+```
+
+### `NotebookApi`
+
+- `create(template, input?, init = true)`
+- `get(id)`
+- `open(id)`
+- `fork(id, input?)`
+- `delete(id)`
+- `openFromData(data)`
+- `mail.status(id)`, `mail.enable(id)`, `mail.disable(id)`, `mail.list(id, options?)`, `mail.get(id, hash)`, `mail.delete(id, hash)`
+
+## `NotebookInstance`
+
+- Lifecycle: `ready()`, `connected()`, `whenConnected()`, `reconnect()`, `dispose()`
+- Notebook actions: `fork(input?)`, `delete()`, `stop()`, `restart()`, `ping()`, `update()`
+- Events: `listen(event, handler)`, `onDidConnect(handler)`, `onDidDisconnect(handler)`, `onDidInitialize(handler)`
+- Raw call: `invoke(action, data?, options?)`
+
+## Services
+
+### Filesystem (`notebook.file`)
+
+- File data: `info()`, `readFile()`, `write()`, `writeFile()`, `tail()`, `stat()`, `exists()`
+- File management: `move()`, `rename()`, `copy()`, `remove()`, `delete()`
+- Directory: `mkdir()`, `createDirectory()`, `readDirectory()`, `tree()`
+- Search: `find()`, `search()`
+- Streaming/monitoring: `watch()`, `download()`
+
+### Terminal (`notebook.terminal`)
+
+- Terminal control: `list()`, `create()`, `attach()`, `resize()`, `input()`
+- Process API: `spawn(command, args, opts?)`, `attach(id, opts?)`
+- Events: `listen()`, `onStarted()`, `onOutput(id, handler)`
+
+### Container (`notebook.container`)
+
+- Lifecycle: `start()`, `stop()`, `state()`
+- Ports: `openedPorts()`, `onPort(handler)`
+- Runtime config: `setPhp(version)`
+- Telemetry: `enableTelemetry(features)`, `stopTelemetry()`, `listen(event, handler)`
+
+### Shell (`notebook.shell`)
+
+- `exec(command)` returning `{ output, exitCode }` plus `throw()` helper
+
+### Services (`notebook.services`)
+
+- Constants: `notebookBuiltinServices`, `notebookKnownServices`
+- `list()`
+- `run(name, command?)`
+- `stop(name)`
+- `logs(name, { tail? })`
+- `logs(name, { follow: true, tail?, id? })` returning `{ id, output, stop() }`
+- Events: `listen()`, `onLog(id, handler)`
+
+### Composer (`notebook.composer`)
+
+- Core: `invoke(command, args?, options?)`
+- Helpers: `install()`, `update()`, `require()`, `remove()`, `dumpAutoload()`, `packages()`, `stream(handler)`
+
+### Git (`notebook.git`)
+
+- `checkpoint(author, message, branch = 'main')`
+- `sync(url, author, ref?, token?, direction?, force?)`
+- `diff({ url?, token?, ref?, base?, target? })`
+- `merge({ url?, token?, ref?, target?, expectedBaseRef?, author?, message? })`
+- `conflicts()`
+- `abortMerge()`
+- `continueMerge(author, message?)`
+- `review()`
+- `stage({ path?, paths?, all? })`
+- `unstage({ path?, paths?, all? })`
+- `revert({ path?, paths?, all?, staged? })`
+- `log(ref = 'main')`
+- `restore(ref)`
+
+### Mail (`notebook.mail`)
+
+- `status()` returning non-sensitive mail configuration state
+- `enable()` enabling SMTP env injection for the notebook
+- `disable()` disabling SMTP env injection and revoking the active SMTP token
+- `list({ page? })` returning paginated notebook mail
+- `get(hash)`
+- `delete(hash)`
+
+### LSP (`notebook.lsp`)
+
+- Messaging: `start(id)`, `close(id)`, `message(id, payload)`
+- Events: `onResponse()`, `onError()`, `onClose()`, `onClientDisconnect()`
+- Connection wrapper: `connection(id)`
+
+### REPL (`notebook.repl`)
+
+- `stop()`, `eval(code, args?, replOpts?)`, `write(input)`, `resize(cols, rows)`
+- Events: `listen()`, `onOutput()`
+
+### Laravel (`notebook.laravel`)
+
+- Wrapper exists in the SDK, but the current okra websocket action set does not expose Laravel maintenance actions.
+
+### Auth (`notebook.auth`)
+
+- `login(newConnectionData)`
+- `logout()`
+
+### Log (`notebook.log`)
+
+- `stream(handler)`
+- `listen(event, handler)`
+
+## Common Errors
+
+- `ApiError` for HTTP API failures
+- `NotebookInitError` when notebook initialization returns `type: 'error'`
+- `FilesystemError` + `FilesystemErrorType.*` for file system operations
+- `RateLimitError` for rate-limited flows
+
+## Notes for Consumers
+
+- `open()` and `get()` do not auto-initialize; call `await notebook.ready()`.
+- `create()` and `fork()` initialize by default.
+- Always call `notebook.dispose()` when finished.

package/docs/cdn-usage.md

@@ -0,0 +1,80 @@
+# CDN Usage Guide
+
+The SDK ships browser bundles under `dist/browser`.
+
+## Security First
+
+Do not hardcode long-lived private API tokens in public frontend code. Use short-lived tokens issued by your backend.
+
+## ESM in Browsers
+
+### unpkg
+
+```html
+<script type="module">
+  import { PHPSandbox } from 'https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js';
+
+  const client = new PHPSandbox('your-short-lived-token');
+  const notebook = await client.notebook.open('your-notebook-id');
+  await notebook.ready();
+
+  const result = await notebook.shell.exec('php -v');
+  result.throw();
+  console.log(result.output);
+</script>
+```
+
+### jsDelivr
+
+```html
+<script type="module">
+  import { PHPSandbox } from 'https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js';
+
+  const client = new PHPSandbox('your-short-lived-token');
+</script>
+```
+
+## Script Tag (IIFE)
+
+### unpkg
+
+```html
+<script src="https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.iife.min.js"></script>
+<script>
+  const client = new PHPSandbox.PHPSandbox('your-short-lived-token');
+
+  client.notebook.open('your-notebook-id').then(async (notebook) => {
+    await notebook.ready();
+    const result = await notebook.shell.exec('php -v');
+    console.log(result.output);
+    notebook.dispose();
+  });
+</script>
+```
+
+### jsDelivr
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.iife.min.js"></script>
+```
+
+## Version Pinning
+
+Always pin a version in production URLs:
+
+```html
+https://unpkg.com/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.esm.min.js
+https://cdn.jsdelivr.net/npm/@phpsandbox/sdk@0.0.51/dist/browser/phpsandbox-sdk.iife.min.js
+```
+
+## Bundle Files
+
+- `phpsandbox-sdk.esm.js`
+- `phpsandbox-sdk.esm.min.js`
+- `phpsandbox-sdk.iife.js`
+- `phpsandbox-sdk.iife.min.js`
+
+## Browser Requirements
+
+- ES2020-compatible runtime
+- `fetch`, `WebSocket`, and `ReadableStream` support

package/docs/getting-started.md

@@ -0,0 +1,152 @@
+# Getting Started with PHPSandbox SDK
+
+This guide walks through the fastest path from install to a working notebook.
+
+## Prerequisites
+
+- Node.js 18+
+- A PHPSandbox API token
+
+## Install
+
+```bash
+npm install @phpsandbox/sdk
+```
+
+## 1. Create a Client
+
+```ts
+import { PHPSandbox } from '@phpsandbox/sdk';
+
+const token = process.env.PHPSANDBOX_TOKEN;
+if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
+
+const client = new PHPSandbox(token);
+```
+
+## 2. Create or Open a Notebook
+
+```ts
+// create() initializes by default
+const notebook = await client.notebook.create('php');
+
+const persistent = await client.notebook.create('laravel', {
+  title: 'Persistent Laravel',
+  persistent: true,
+});
+
+// open()/get() need ready()
+const existing = await client.notebook.open('notebook-id');
+await existing.ready();
+
+const fork = await existing.fork();
+const persistentFork = await existing.fork({ persistent: true });
+```
+
+API notebook creates and forks are ephemeral by default. Use `persistent: true` only when your account is allowed to create persistent notebooks.
+
+## 3. Write and Read Files
+
+```ts
+await notebook.file.write('hello.php', '<?php echo "Hello";');
+
+const data = await notebook.file.readFile('hello.php');
+const text = new TextDecoder().decode(data);
+
+console.log(text);
+```
+
+If you need binary-safe writes, use `writeFile`:
+
+```ts
+await notebook.file.writeFile('binary.dat', new Uint8Array([1, 2, 3]), {
+  create: true,
+  overwrite: true,
+  unlock: false,
+  atomic: false,
+});
+```
+
+## 4. Run Commands
+
+### Terminal (stream output)
+
+```ts
+const task = await notebook.terminal.spawn('php', ['hello.php']);
+const reader = task.output.getReader();
+
+try {
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    process.stdout.write(value);
+  }
+} finally {
+  reader.releaseLock();
+}
+
+const exitCode = await task.exit;
+console.log(`\nExit code: ${exitCode}`);
+```
+
+### Shell (single command result)
+
+```ts
+const result = await notebook.shell.exec('php -v');
+result.throw();
+console.log(result.output);
+```
+
+## 5. Search and Watch Files
+
+```ts
+const matches = await notebook.file.find('*.php', {
+  includes: ['app/**'],
+  excludes: ['vendor/**'],
+});
+
+console.log(matches.map((m) => m.path));
+
+const watcher = notebook.file.watch(
+  '/app',
+  {
+    recursive: true,
+    excludes: ['vendor/**', 'node_modules/**'],
+  },
+  (change) => {
+    console.log(change.type, change.path);
+  }
+);
+
+// later
+watcher.dispose();
+```
+
+## 6. Use Composer and Git
+
+```ts
+await notebook.composer.install({ noInteraction: true });
+await notebook.composer.require({ packages: ['monolog/monolog'] });
+
+await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
+```
+
+## 7. Clean Up
+
+Always dispose notebook connections when finished:
+
+```ts
+notebook.dispose();
+```
+
+## Common Pitfalls
+
+- `open()` / `get()` notebooks must call `await notebook.ready()` before tool calls.
+- `file.watch()` requires an `excludes` array.
+- `shell.exec()` does not throw by default; call `result.throw()` to fail on non-zero exit codes.
+
+## Next Reading
+
+- API overview: `docs/api-summary.md`
+- CDN/browser usage: `docs/cdn-usage.md`
+- Root quick start: `README.md`