@phpsandbox/sdk 0.1.9 → 0.1.11

package/docs/getting-started.md

@@ -5,7 +5,8 @@ This guide walks through the fastest path from install to a working notebook.
 ## Prerequisites
 
 - Node.js 18+
-- A PHPSandbox API token
+- A PHPSandbox account with an active subscription and available notebook capacity
+- SDK access enabled and an API key created in **API keys**
 
 ## Install
 
@@ -13,6 +14,10 @@ This guide walks through the fastest path from install to a working notebook.
 npm install @phpsandbox/sdk
 ```
 
+Copy the API key when shown and store it in `PHPSANDBOX_TOKEN` in your server environment or secret store. Keys are shown once and grant notebook read and write access; never include them in frontend bundles or commit them. If **API keys** is unavailable, request SDK access first.
+
+For a complete runnable example, save the [root quick start](../README.md#quick-start) as `quickstart.mjs` and run `node quickstart.mjs`. The snippets below explain individual operations.
+
 ## 1. Create a Client
 
 ```ts
@@ -21,23 +26,20 @@ import { PHPSandbox } from '@phpsandbox/sdk';
 const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
 
-const client = new PHPSandbox(token);
+const client = PHPSandbox.realtime(token);
 ```
 
 ## 2. Create or Open a Notebook
 
 ```ts
-// create() initializes by default
-const notebook = await client.notebook.create('php');
+const notebook = await client.notebook.create('standard');
 
 const persistent = await client.notebook.create('laravel', {
   title: 'Persistent Laravel',
   persistent: true,
 });
 
-// get() needs ready()
 const existing = await client.notebook.get('notebook-id');
-await existing.ready();
 
 const fork = await existing.fork();
 const persistentFork = await existing.fork({ persistent: true });
@@ -75,15 +77,12 @@ await notebook.files.write('binary.dat', new Uint8Array([1, 2, 3]), {
 const task = await notebook.terminals.create({ command: 'php', args: ['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();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  process.stdout.write(value);
 }
+reader.releaseLock();
 
 const exitCode = await task.wait();
 console.log(`\nExit code: ${exitCode}`);
@@ -93,7 +92,7 @@ console.log(`\nExit code: ${exitCode}`);
 
 ```ts
 const result = await notebook.exec('php -v', { tty: false });
-result.throw();
+if (result.exitCode !== 0) throw new Error(result.stderr || result.output);
 console.log(result.stdout);
 ```
 
@@ -105,9 +104,9 @@ const matches = await notebook.files.find('*.php', {
   excludes: ['vendor/**'],
 });
 
-console.log(matches.map((m) => m.path));
+console.log(matches.map((match) => match.path));
 
-const watcher = notebook.files.watch(
+const watcher = await notebook.files.watch(
   '/app',
   {
     recursive: true,
@@ -125,28 +124,46 @@ watcher.dispose();
 ## 6. Use Composer and Git
 
 ```ts
-(await notebook.composer.install().wait()).throw();
-(await notebook.composer.require({ packages: ['monolog/monolog'] }).wait()).throw();
+const installResult = await notebook.composer.run('install').wait();
+if (installResult.exitCode !== 0) throw new Error(installResult.stderr || installResult.output);
+
+const requireResult = await notebook.composer.run('require', { packages: ['monolog/monolog'] }).wait();
+if (requireResult.exitCode !== 0) throw new Error(requireResult.stderr || requireResult.output);
 
 await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
 ```
 
 ## 7. Clean Up
 
-Always dispose notebook connections when finished:
+Use a `finally` block to dispose every connection, including forks and notebooks opened with `get()`. `dispose()` only closes local resources. For temporary automation, delete the remote notebook as well:
 
 ```ts
-notebook.dispose();
+try {
+  await notebook.destroy();
+} finally {
+  notebook.dispose();
+}
 ```
 
+Omit `destroy()` only when you intend to keep the notebook. Stopping a notebook does not delete it. Ephemeral notebooks are eventually pruned according to `notebook.data.policy`; do not rely on that as immediate cleanup.
+
 ## Common Pitfalls
 
-- `get()` notebooks must call `await notebook.ready()` before tool calls.
+- Runtime actions wait for readiness. Call `ready()` only when you need its provisioning metadata.
 - `files.watch()` requires an `excludes` array.
-- Use `notebook.exec()` for one-shot commands; for streaming shell handles, await `process.wait()` and call `result.throw()` to fail on non-zero exit codes.
+- Command results include `exitCode`; decide explicitly whether a non-zero exit should fail your workflow.
+
+## Troubleshooting
+
+- `401`: check that the API key is set and has not been revoked.
+- `403`: check permissions, account subscription, notebook capacity, and persistence entitlement.
+- `404`: the notebook is missing or inaccessible to your account.
+- `422`: use `RemoteError.isValidation(error)` to inspect field errors; `standard` is the plain PHP template ID.
+- `429`: respect `error.response.headers.get('Retry-After')` and reduce concurrency. Avoid blind retries of resource creation or publication.
+- A process stays alive after the script finishes: ensure all notebook instances are disposed in `finally`.
 
 ## Next Reading
 
-- API overview: `docs/api-summary.md`
-- CDN/browser usage: `docs/cdn-usage.md`
-- Root quick start: `README.md`
+- API overview: [API overview](api-summary.md)
+- CDN/browser usage: [Browser usage](cdn-usage.md)
+- Root quick start: [Root quick start](../README.md)

package/examples/README.md

@@ -1,5 +1,7 @@
 ## Examples
 
+Examples import the published `@phpsandbox/sdk` package. From a source checkout, run `npm ci && npm run build` first. Set `PHPSANDBOX_TOKEN` using your environment or secret store. The basic example creates and deletes one temporary notebook; publication examples can change deployments and provider resources.
+
 ### Running Basic Example
 
 ```bash
@@ -97,7 +99,7 @@ Useful flags:
 - `--no-cleanup` keeps every notebook after the run.
 - `--keep-failed` keeps failed notebooks for inspection. By default, failures are deleted too.
 - `--runtime-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes runtime traffic to another host.
-- `--include-container-restart` adds a mutable `container.start()` restart check on the fresh notebook.
+- `--include-container-restart` adds a runtime restart check on the fresh notebook.
 - `--include-download` adds `file.download()` to the baseline.
 - `--include-preview` fetches the initialized preview URL in init mode, or the route written by the scenario in full mode.
 - `--include-lsp` adds an LSP initialize handshake to the baseline.
@@ -196,38 +198,6 @@ PHPSANDBOX_TOKEN=your-token npx tsx examples/git-merge-smoke.ts \
 
 By default the created fork is kept for inspection. Pass `--delete-fork` when you want the script to delete it after the run.
 
-### Okra Operator Loop
-
-For repeatable prod investigations, use the operator CLI:
-
-```bash
-npx tsx tools/okra-loop.ts run --label=init-64-96 -- --levels=64,80,96 --waves=2 --mode=init
-```
-
-If you omit the load-test level flags entirely, the operator loop defaults to a conservative staircase:
-
-```bash
-npx tsx tools/okra-loop.ts run --label=quick-probe
-```
+### Repository-only operator tools
 
-That default probe uses `--levels=1,2,4,8,12,16,24,32,48,64,80,96` and enables `--stop-on-failure-level` so you get the first failing boundary quickly.
-
-This will:
-
-- run the Laravel load test and save `load-test.json`, stdout, and stderr into `artifacts/okra-loop/<timestamp>-<label>/`
-- capture before/after snapshots from `okra-main`, `okra-helfer`, and `okra-helfer-prime`
-- sample remote load/memory/supervisor state during the run
-- write `analysis.json` plus a `report.md` with hotspot heuristics and next actions
-
-Useful operator flags:
-
-- `--hosts=none` disables SSH collection, which is useful for local API runs.
-- `--deploy-hosts=workers` deploys the local okra checkout to `okra-helfer` and `okra-helfer-prime` before the run.
-- `--artifact-root=...` changes where run artifacts are stored.
-- `--sample-interval-ms=15000` adjusts the SSH sampling interval.
-
-Deploy only:
-
-```bash
-npx tsx tools/okra-loop.ts deploy --deploy-hosts=workers
-```
+The `tools/okra-loop.ts` operator utility requires the source checkout and maintainer infrastructure access. It is not included in the published package and is not part of consumer onboarding.

package/examples/basic.ts

@@ -1,24 +1,15 @@
-import { PHPSandbox } from '../src/index.js';
+import { PHPSandbox } from '@phpsandbox/sdk';
 
 const token = process.env.PHPSANDBOX_TOKEN;
-if (!token) {
-  throw new Error('Missing PHPSANDBOX_TOKEN');
-}
+if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
 
-const psb = new PHPSandbox(token);
-const notebook = await psb.notebook.create('laravel');
+const client = PHPSandbox.realtime(token);
+const notebook = await client.notebook.create('standard');
 
-console.log('====== Ping the notebook ======');
-console.log('Response:', await notebook.ping());
-console.log('====== Notebook is ready ======');
+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());
 
-console.log('\n');
-
-console.log('====== Read routes/web.php in the notebook ======');
-const decoder = new TextDecoder();
-const content = await notebook.files.read('routes/web.php');
-console.log(decoder.decode(content));
-
-// Always close the notebook when done to clean up the connection.
-notebook.dispose();
 await notebook.destroy();
+notebook.dispose();

package/examples/get.ts

@@ -1,4 +1,4 @@
-import { Client } from '../src/index.js';
+import { PHPSandbox } from '@phpsandbox/sdk';
 
 const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) {
@@ -11,7 +11,7 @@ if (!notebookId) {
 }
 
 const apiUrl = process.env.PHPSANDBOX_API_URL ?? 'https://api.phpsandbox.io/v1';
-const client = new Client(token, apiUrl);
+const client = PHPSandbox.realtime(token, apiUrl);
 const notebook = await client.notebook.get(notebookId);
 
 try {

package/examples/git-merge-smoke.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import https from 'node:https';
 import axios from 'axios';
 import NodeWebSocket from 'ws';
-import { PHPSandbox, type GitDiffPreview, type GitMergeResult, type NotebookInstance } from '../src/index.js';
+import { PHPSandbox, type GitDiffPreview, type GitMergeResult, type NotebookInstance } from '@phpsandbox/sdk';
 
 const DEFAULT_API_URL = 'https://api.phpsandbox.io/v1';
 const DEFAULT_LOCAL_API_URL = 'https://api.phpsandbox.test/v1';
@@ -31,8 +31,7 @@ interface Options {
 async function main(): Promise<void> {
   const options = parseOptions(process.argv.slice(2));
   const transport = await createNodeTransport(options);
-  const client = new PHPSandbox(options.token, options.apiUrl, {
-    startClosed: true,
+  const client = PHPSandbox.realtime(options.token, options.apiUrl, {
     ...transport,
   });
 

package/examples/laravel-load-test.ts

@@ -1,7 +1,6 @@
 import fs from 'node:fs/promises';
 import https from 'node:https';
 import {
-  type ContainerStats,
   type Disposable,
   type FileChange,
   type NotebookInitProgress,
@@ -12,7 +11,8 @@ import {
   NotebookInstance,
   type PortInfo,
   PHPSandbox,
-} from '../src/index.js';
+  RemoteError,
+} from '@phpsandbox/sdk';
 import axios from 'axios';
 import NodeWebSocket from 'ws';
 
@@ -72,7 +72,6 @@ interface LoadTestOptions {
   cleanup: boolean;
   keepFailed: boolean;
   debug: boolean;
-  startClosed: boolean;
   stepTimeoutMs: number;
   streamTimeoutMs: number;
   telemetryTimeoutMs: number;
@@ -255,9 +254,8 @@ async function main(): Promise<void> {
   const transport = await createNodeTransport(options);
   const ui = new LoadTestUi(options);
   const interrupts = new InterruptController();
-  const client = new PHPSandbox(options.token, options.apiUrl, {
+  const client = PHPSandbox.realtime(options.token, options.apiUrl, {
     debug: options.debug,
-    startClosed: options.startClosed,
     fetch: transport.fetch,
     webSocket: transport.webSocket,
   });
@@ -471,8 +469,7 @@ async function runScenario(
           {
             title: `${options.titlePrefix} ${id}`,
             visibility: options.visibility,
-          },
-          false
+          }
         );
 
         const data = {
@@ -481,7 +478,7 @@ async function runScenario(
         };
         created.dispose();
 
-        return new NotebookInstance(data, client);
+        return client.notebook.open(data);
       },
       { continueOnError: false }
     );
@@ -559,7 +556,7 @@ async function runScenario(
     }
 
     if (options.mode !== 'init') {
-      logReader = notebook.logs.follow().getReader();
+      logReader = notebook.runtime.logs.follow().getReader();
       void (async () => {
         while (logReader) {
           const entry = await logReader.read();
@@ -573,20 +570,18 @@ async function runScenario(
         }
       })().catch(() => {});
 
-      await runCheckedStep('notebook.ping', () => notebook!.ping(), { continueOnError: false });
-
       await runCheckedStep('notebook.secrets', async () => {
         return secretsStepLimiter.run(async () => {
           await retryWithBackoff(
             () => notebook!.secrets.set(secretName, `value-${id}`),
             SECRETS_RETRY_DELAYS_MS,
-            shouldRetryApiRateLimitError
+            shouldRetryRemoteRateLimitError
           );
 
           const secrets = await retryWithBackoff(
             () => notebook!.secrets.list(),
             SECRETS_RETRY_DELAYS_MS,
-            shouldRetryApiRateLimitError
+            shouldRetryRemoteRateLimitError
           );
 
           const found = secrets.find((secret) => secret.name === secretName);
@@ -597,29 +592,25 @@ async function runScenario(
           await retryWithBackoff(
             () => notebook!.secrets.delete(secretName),
             SECRETS_RETRY_DELAYS_MS,
-            shouldRetryApiRateLimitError
+            shouldRetryRemoteRateLimitError
           );
 
           return secrets.length;
         });
       });
 
-      await runCheckedStep('container.state', async () => {
-        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
-        const portInfo = assertPortInfoList(ports, 'ports.list');
-        return `${state.state} (${describePorts(portInfo)})`;
+      await runCheckedStep('container.ports', async () => {
+        const ports = await notebook!.runtime.ports.list();
+        return describePorts(assertPortInfoList(ports, 'ports.list'));
       });
 
       if (options.includeContainerRestart) {
         await runCheckedStep(
           'container.restart',
           async () => {
-            await notebook!.container.start();
-            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
-            if (state.state !== 'running') {
-              throw new Error(`Expected running container after restart, got ${state.state}`);
-            }
-            return `${state.state} (${describePorts(assertPortInfoList(ports, 'ports.list after restart'))})`;
+            await notebook!.restart();
+            const ports = await notebook!.runtime.ports.list();
+            return describePorts(assertPortInfoList(ports, 'ports.list after restart'));
           },
           { timeoutMs: options.stepTimeoutMs * 3, continueOnError: false }
         );
@@ -632,8 +623,8 @@ async function runScenario(
         async () =>
           retryWithBackoff(
             async () => {
-              const statsReader = notebook!.metrics.watch().getReader();
-              const portsReader = notebook!.ports.watch().getReader();
+              const statsReader = notebook!.runtime.metrics.watch().getReader();
+              const portsReader = notebook!.runtime.ports.watch().getReader();
               try {
                 const statsPromise = withTimeout(statsReader.read(), options.telemetryTimeoutMs, 'metrics.watch')
                   .then(({ value }) => {
@@ -741,7 +732,9 @@ async function runScenario(
 
       await runCheckedStep('shell.run', async () => {
         const result = await notebook!.run(['php', 'artisan', '--version']).wait();
-        result.throw();
+        if (result.exitCode !== 0) {
+          throw new Error(result.stderr || result.output);
+        }
         if (!result.output.toLowerCase().includes('laravel')) {
           throw new Error(`Unexpected artisan version output: ${trimDetail(result.output)}`);
         }
@@ -768,7 +761,9 @@ async function runScenario(
             withTimeout(execution.wait(), options.stepTimeoutMs, 'waiting for process exit'),
           ]);
 
-          result.throw();
+          if (result.exitCode !== 0) {
+            throw new Error(result.stderr || result.output);
+          }
           const combined = [streamOutput, result.output].filter(Boolean).join('\n');
           if (!combined.includes(routeUrlPath)) {
             throw new Error(`route:list output did not contain ${routeUrlPath}.`);
@@ -842,14 +837,17 @@ async function runScenario(
 
       await runCheckedStep('composer.metadata', async () => {
         let composerLogChunks = 0;
-        const dump = notebook!.composer.dumpAutoload();
+        const dump = notebook!.composer.run('dump-autoload');
         for await (const chunk of dump.output) {
           if (chunk.data.byteLength > 0) {
             composerLogChunks += 1;
           }
         }
 
-        (await dump.wait()).throw();
+        const result = await dump.wait();
+        if (result.exitCode !== 0) {
+          throw new Error(result.stderr || result.output);
+        }
         const packages = await notebook!.composer.packages();
         if (packages.length === 0) {
           throw new Error('composer.packages() returned no packages.');
@@ -1002,7 +1000,7 @@ async function cleanupNotebook(notebook: NotebookInstance, steps: StepResult[]):
       const notebookId = notebook.data.id;
       await cleanupDeleteLimiter.run(async () => {
         try {
-          await retryWithBackoff(() => notebook.destroy(), DELETE_RETRY_DELAYS_MS, shouldRetryApiRateLimitError);
+          await retryWithBackoff(() => notebook.destroy(), DELETE_RETRY_DELAYS_MS, shouldRetryRemoteRateLimitError);
         } catch (error) {
           if (formatError(error).includes('Notebook has been deleted')) {
             return;
@@ -1059,7 +1057,6 @@ function renderConfiguration(options: LoadTestOptions): string {
     `  waves per level: ${options.waves}`,
     `  visibility: ${options.visibility}`,
     `  cleanup: ${options.cleanup} (keep failed: ${options.keepFailed})`,
-    `  startClosed: ${options.startClosed}`,
     `  include container restart: ${options.includeContainerRestart}`,
     `  include download: ${options.includeDownload}`,
     `  include preview: ${options.includePreview}`,
@@ -2120,9 +2117,8 @@ function formatError(error: unknown): string {
   return String(error);
 }
 
-function shouldRetryApiRateLimitError(error: unknown): boolean {
-  const message = formatError(error);
-  return message.includes('429') || message.includes('Too Many Attempts');
+function shouldRetryRemoteRateLimitError(error: unknown): boolean {
+  return RemoteError.is(error, 'RateLimited');
 }
 
 function shouldRetryTelemetryError(error: unknown): boolean {
@@ -2395,7 +2391,6 @@ function parseOptions(argv: string[]): LoadTestOptions {
     cleanup: booleanArg(args, 'cleanup') ?? true,
     keepFailed: booleanArg(args, 'keep-failed') ?? false,
     debug: booleanArg(args, 'debug') ?? false,
-    startClosed: booleanArg(args, 'start-closed') ?? true,
     stepTimeoutMs: numberArg(args, 'step-timeout-ms') ?? 60_000,
     streamTimeoutMs: numberArg(args, 'stream-timeout-ms') ?? 20_000,
     telemetryTimeoutMs: numberArg(args, 'telemetry-timeout-ms') ?? 15_000,

package/examples/notebook-readonly-smoke.ts

@@ -10,7 +10,7 @@ import {
   type NotebookInitProgress,
   type NotebookInitResult,
   type PortInfo,
-} from '../src/index.js';
+} from '@phpsandbox/sdk';
 
 const DEFAULT_API_URL = 'https://api.phpsandbox.io/v1';
 const DEFAULT_LOCAL_API_URL = 'https://api.phpsandbox.test/v1';
@@ -30,7 +30,6 @@ interface SmokeOptions {
   includeDownload: boolean;
   includePreview: boolean;
   debug: boolean;
-  startClosed: boolean;
   insecureTls: boolean;
   caFile?: string;
   stepTimeoutMs: number;
@@ -89,9 +88,8 @@ async function main(): Promise<void> {
   const steps: StepArtifact[] = [];
   const initTrace: InitTraceArtifact = { events: [] };
   const transport = await createNodeTransport(options);
-  const client = new PHPSandbox(options.token, options.apiUrl, {
+  const client = PHPSandbox.realtime(options.token, options.apiUrl, {
     debug: options.debug,
-    startClosed: options.startClosed,
     ...transport,
   });
 
@@ -100,7 +98,8 @@ async function main(): Promise<void> {
 
   try {
     const response = await recordStep(steps, 'api.get-notebook', options.stepTimeoutMs, async () => {
-      const result = await client.get<NotebookData>(`/notebook/${options.notebookId}`);
+      const result = await client.notebook.get(options.notebookId);
+      result.dispose();
       return {
         data: result.data,
         detail: `id=${result.data.id} type=${result.data.type ?? ''} title=${result.data.title ?? ''} runtimeUrl=${redactUrl(result.data.runtimeUrl)}`,
@@ -112,7 +111,7 @@ async function main(): Promise<void> {
       runtimeUrl: resolveRuntimeUrl(response.data.runtimeUrl, options),
     };
 
-    notebook = new NotebookInstance(notebookData, client);
+    notebook = client.notebook.open(notebookData);
     const initStartedAt = performance.now();
     notebook.listen('init.event', (event: NotebookInitProgress) => {
       initTrace.events.push({
@@ -138,24 +137,8 @@ async function main(): Promise<void> {
     });
     const ready = readyStep.result;
 
-    await recordStep(steps, 'notebook.ping', options.stepTimeoutMs, async () => {
-      const result = await notebook!.ping();
-      if (result !== 'pong') {
-        throw new Error(`Expected pong, got ${String(result)}`);
-      }
-      return result;
-    }, false);
-
-    await recordStep(steps, 'container.state', options.stepTimeoutMs, async () => {
-      const state = await notebook!.container.state();
-      if (!state || typeof state.state !== 'string') {
-        throw new Error(`Unexpected container.state response: ${JSON.stringify(state)}`);
-      }
-      return state.state;
-    }, false);
-
     await recordStep(steps, 'container.opened-ports', options.stepTimeoutMs, async () => {
-      const ports = await notebook!.ports.list();
+      const ports = await notebook!.runtime.ports.list();
       return describePorts(assertPortInfoList(ports, 'ports.list'));
     }, false);
 
@@ -186,7 +169,9 @@ async function main(): Promise<void> {
         notebook!.files.find('composer.json', { maxResults: 10 }),
         notebook!.files.find('index.php', { maxResults: 10 }),
       ]);
-      const candidate = [...composerFiles, ...indexFiles].find((file) => typeof file.path === 'string')?.path;
+      const candidate = [...composerFiles, ...indexFiles]
+        .find((file) => typeof file.path === 'string')
+        ?.path;
       return {
         detail: `composerFiles=${composerFiles.length} indexFiles=${indexFiles.length}`,
         candidate,
@@ -326,7 +311,9 @@ async function main(): Promise<void> {
 async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifact[], options: SmokeOptions): Promise<void> {
   await recordStep(steps, 'shell.run', options.stepTimeoutMs, async () => {
     const result = await notebook.run(['php', '-r', 'echo "sdk-smoke";']).wait();
-    result.throw();
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || result.output);
+    }
     if (!result.output.includes('sdk-smoke')) {
       throw new Error(`Unexpected shell output: ${result.output}`);
     }
@@ -511,7 +498,6 @@ function parseOptions(argv: string[]): SmokeOptions {
     includeDownload: booleanArg(args, 'include-download') ?? false,
     includePreview: booleanArg(args, 'include-preview') ?? false,
     debug: booleanArg(args, 'debug') ?? false,
-    startClosed: booleanArg(args, 'start-closed') ?? true,
     insecureTls: booleanArg(args, 'insecure-tls') ?? ((booleanArg(args, 'local') ?? false) && !stringArg(args, 'ca-file')),
     caFile: stringArg(args, 'ca-file'),
     stepTimeoutMs: numberArg(args, 'step-timeout-ms') ?? 60_000,

package/examples/publication-provider-label.ts

@@ -1,4 +1,4 @@
-import type { PublicationProviderName } from '../src/index.js';
+import type { PublicationProviderName } from '@phpsandbox/sdk';
 
 const publicationProviderLabels: Record<PublicationProviderName, string> = {
   'cloudflare-containers': 'Cloudflare Containers',

package/examples/publish-cloudflare-container.ts

@@ -1,4 +1,4 @@
-import { Client } from '../src/index.js';
+import { PHPSandbox } from '@phpsandbox/sdk';
 import { publicationProviderLabel } from './publication-provider-label.js';
 
 const token = process.env.PHPSANDBOX_TOKEN;
@@ -18,7 +18,7 @@ const cloudflareApiToken = process.env.CLOUDFLARE_API_TOKEN;
 if (!cloudflareAccountId || !cloudflareApiToken) {
   throw new Error('Missing CLOUDFLARE_ACCOUNT_ID or CLOUDFLARE_API_TOKEN');
 }
-const client = new Client(token, apiUrl);
+const client = PHPSandbox.realtime(token, apiUrl);
 const notebook = await client.notebook.get(notebookId);
 
 try {

package/examples/publish-laravel-cloud.ts

@@ -1,4 +1,4 @@
-import { Client, type Integration, type LaravelCloudRegion } from '../src/index.js';
+import { PHPSandbox, type Integration, type LaravelCloudRegion } from '@phpsandbox/sdk';
 import { publicationProviderLabel } from './publication-provider-label.js';
 
 const token = process.env.PHPSANDBOX_TOKEN;
@@ -19,7 +19,7 @@ if (new URL(apiUrl).hostname.endsWith('.test') && process.env.NODE_TLS_REJECT_UN
   process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 }
 
-const client = new Client(token, apiUrl);
+const client = PHPSandbox.realtime(token, apiUrl);
 const notebook = await client.notebook.get(notebookId);
 
 try {

package/examples/publish-ssh-agent.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Client, type ServerInstance } from '../src/index.js';
+import { PHPSandbox, type ServerInstance } from '@phpsandbox/sdk';
 import { publicationProviderLabel } from './publication-provider-label.js';
 
 const token = process.env.PHPSANDBOX_TOKEN;
@@ -24,7 +24,7 @@ if (isLocal && process.env.NODE_TLS_REJECT_UNAUTHORIZED === undefined) {
   process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 }
 
-const client = new Client(token, apiUrl);
+const client = PHPSandbox.realtime(token, apiUrl);
 const notebook = await client.notebook.get(notebookId);
 let agent: ChildProcessWithoutNullStreams | null = null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -43,8 +43,9 @@
     "smoke:reaper": "npm run build:tsc && vitest run --reporter=verbose --config tests/smoke/vitest.config.ts tests/smoke/maintenance/resources.reaper.smoke.ts",
     "smoke:typecheck": "npm run build:tsc && tsc --project tests/smoke/tsconfig.json --noEmit",
     "check:examples": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2020 --types node --skipLibCheck --allowSyntheticDefaultImports --esModuleInterop examples/basic.ts examples/publish-cloudflare-container.ts examples/publish-laravel-cloud.ts examples/publish-ssh-agent.ts examples/get.ts examples/git-merge-smoke.ts examples/laravel-load-test.ts examples/notebook-readonly-smoke.ts",
-    "prepublishOnly": "npm test && npm run check:examples && npm run clean && npm run build",
-    "bumpAndPublish": "npm version patch && npm publish --access public"
+    "prepublishOnly": "npm test && npm run check:examples && npm run check:docs && npm run clean && npm run build",
+    "bumpAndPublish": "npm version patch && npm publish --access public",
+    "check:docs": "npm run build:tsc && node tools/check-documentation.mjs"
   },
   "keywords": [
     "php",